背景与需求分析
为什么需要把 MongoDB 文档转换为数组
在 Symfony 项目中，查询 MongoDB 的结果常以 BSON 文档的形式返回，这类结构在直接输出或传输时往往不易使用。将文档转换为 PHP 数组，能够提供更统一的处理方式，包括序列化成 JSON、参与数据聚合、以及与前端接口的对接。数组形式更易于遍历、变换和缓存，降低了后续编码成本。
通过将文档转换为数组，开发者可以在控制器、服务层和模板之间安全地传递数据，避免在视图层进行复杂的对象访问，从而提升可维护性与性能。对于 API 输出，数组也是最常用的序列化入口。
在 Symfony 项目中的常见场景
场景一：将查询结果渲染成 JSON API，需要把文档集合转换为数组后再使用 JsonResponse 返回给客户端。数组结构是可控的 JSON 序列化基础，能够避免对象中的不可序列化成员带来的问题。
场景二：数据导出与离线分析，将 MongoDB 的文档集合转换为数组后，可以写入 CSV/Excel 或导出为数据湖格式。统一的数据结构便于后续处理。
实现方案概览
使用 Doctrine ODM 还是 MongoDB 官方驱动
两者都可以实现文档到数组的转换，但方式不同：Doctrine MongoDB ODM 更偏向对象映射，查询结果通常是文档对象，需要额外的 toArray 或自定义转换；官方驱动（mongodb/mongodb）返回的通常是 BSONDocument 或可迭代的对象，具备更直接的转换入口。选择应基于项目现状与团队熟悉度。
两者在数组转换中的差异
官方驱动的结果对象通常提供底层转换接口，如 getArrayCopy()，可直接得到数组；若未暴露该接口，则需要进行 JSON Round-Trip 转换。Doctrine ODM 需要以实体对象方式遍历后再转成数组，通常需要自定义 toArray 方法，以确保嵌套结构也能正确展平。
具体实现步骤与代码示例
准备工作：安装驱动与配置
先安装 MongoDB 官方 PHP 库，以获得对 BSON 的原生支持与高效遍历能力。在 Symfony 项目中，常用的做法是通过 Composer 安装：composer require mongodb/mongodb，并确保 autoload 加载正常。
还原可用的连接方式，示例中使用 MongoDB\Client 的简洁入口来获取集合对象，后续用于文档遍历与转换。合理的连接配置有助于性能调优。
selectCollection('mydb', 'mycollection');
$cursor = $collection->find([]);
?>从 MongoDB 文档获取为 PHP 数组的核心方法
核心思路是对游标中的每个文档进行转换，优先尝试使用原生能力直接获取数组；若文档对象不具备直接转换接口，则回退到安全的 JSON 转换。确保嵌套结构也能正确处理。
getArrayCopy();continue;}// 兜底：通过 JSON 转换为数组，注意日期/二进制等类型需要后续处理$results[] = json_decode(json_encode($doc), true);
}// 结果：$results 为一维数组的文档数组
?> 在实际的 Symfony 控制器或服务中，可以把上述逻辑做成幂等的服务方法，方便复用与单元测试。下面给出一个在控制器中的简化示例，用于将查询结果直接输出为 JSON。
selectCollection('mydb', 'mycollection');$cursor = $collection->find([]);$docsAsArray = [];foreach ($cursor as $doc) {if (method_exists($doc, 'getArrayCopy')) {$docsAsArray[] = $doc->getArrayCopy();} else {$docsAsArray[] = json_decode(json_encode($doc), true);}}return new Symfony\Component\HttpFoundation\JsonResponse($docsAsArray);
}
?> 处理 BSON/对象与数组的边界情况
某些字段的类型在转换时会发生变化，如 ObjectId、UTCDateTime 等，在输出给前端或写入文件时需保持可处理性。对关键字段进行显式规范化，是稳定性的关键。
getArrayCopy();}// 递归处理可序列化的嵌套结构if (is_array($doc)) {return array_map('bsonDocToArray', $doc);}return json_decode(json_encode($doc), true);
}
?> 示例中的转换入口函数 bsonDocToArray() 可以在集合转换时被调用，确保结构一致性。
实战演练：完整示例
场景1：简单文档转数组
场景1 的目标是将简单平面文档转成一组数组，便于 API 输出或二次处理。通过游标逐条转换，避免一次性占用大量内存。逐条转换也便于错误隔离。
selectCollection('shop', 'orders');
$cursor = $collection->find(['status' => 'paid'], ['limit' => 100]);$flatList = [];
foreach ($cursor as $doc) {if (method_exists($doc, 'getArrayCopy')) {$flatList[] = $doc->getArrayCopy();} else {$flatList[] = json_decode(json_encode($doc), true);}
}
?> 场景2：嵌套文档和数组的转化
当文档中包含嵌套文档或数组时，需递归转换以保持结构完整。可以通过辅助函数实现递归处理，确保前端可以直接消费。
getArrayCopy();}if (is_array($val)) {return array_map('recursiveConvert', $val);}return $val;
}$client = new MongoClient('mongodb://localhost:27017');
$collection = $client->selectCollection('shop', 'customers');
$cursor = $collection->find([]);$result = [];
foreach ($cursor as $doc) {$result[] = recursiveConvert($doc);
}
?> 性能与内存考虑
逐条转换比一次性把整组文档加载到内存中更友好，特别是在大数据量场景中。使用游标逐步处理、分页查询或批量输出，能降低峰值内存占用。
如果必须一次性输出全部数据，请确保服务器内存足以承载数据量，并考虑对数据进行分块输出或流式传输，以避免内存膨胀。也可以借助 Symfony 的流式响应来实现。
常见坑与调优要点
字段的类型转换
ObjectId、UTCDateTime 等 BSON 类型在转换为数组时容易变成字符串或数组结构，如果需要保持特定格式，请在转换后进行字段规范化。例如将 _id 转为字符串，日期转成 ISO8601 字符串，以保持前后端的一致性。
toDateTime()->format(DATE_RFC3339);}return $doc;
}
?> 日期/二进制数据的处理
日期类型要统一输出格式，二进制数据要避免直接二次序列化，若有二进制字段，优先转换为可识别的文本表示或使用 base64 编码。这能提升跨系统互操作性。
本文围绕 如何在 Symfony 中把 MongoDB 文档转换为数组？ 进行详解与实战，覆盖从环境准备、核心转换方法、到具体代码实现的完整路径。通过上述示例与要点，可以在实际项目中快速落地，将 MongoDB 文档顺畅转化为可操作的数组结构，服务于 API、数据导出、以及前后端的数据协作。
