PHP操作MongoDB必须使用mongodb扩展配合mongodb/mongodb库，确保类型安全与协议兼容；扩展需与PHP版本、架构及MongoDB服务端对齐，连接字符串须带mongodb://前缀并正确配置认证与超时参数，所有操作必须使用BSON类型而非JSON字符串或裸数组。
PHP 操作 MongoDB 必须用 mongodb 扩展（不是已废弃的 mongo），配合 mongodb/mongodb 封装库才能写出可维护、类型安全、符合现代协议的代码。只装扩展不装库，或反过来，都会卡在 BSON 类型处理、连接管理或查询构造上。
确认 mongodb 扩展已正确加载且版本兼容
很多“连不上”“Class not found”问题其实卡在这一步。扩展必须和 PHP 版本（TS/NTS）、架构（x86/x64）、MongoDB 服务端协议（4.0+）对齐：
- 运行
php -m | grep mongodb，有输出才说明扩展已启用；没输出就别往下试 - 检查是否误装了旧版
mongo扩展：它会在phpinfo()里显示mongo模块，但调用MongoDB\Client会报错Class 'MongoDB\Client' not found - Windows 用户特别注意 DLL 文件名：必须是
php_mongodb.dll（不是php_mongo.dll），且要匹配 PHP 的线程安全标识（ts或nts）和位数 -
php -r "var_dump(extension_loaded('mongodb'));"返回bool(true)是最低验证门槛
用 MongoDB\Client 连接时字符串格式和惰性触发机制
MongoDB\Client 不是传统意义上的“打开连接”，它只是配置好参数，真正建连发生在第一次读写操作时。这个特性常被误读为“连接成功”，结果 find() 或 insertOne() 才暴露认证失败或超时问题：
- 连接字符串必须带
mongodb://前缀，localhost:27017不能简写成127.0.0.1（DNS 解析差异可能影响副本集发现） - 带认证时格式为
mongodb://user:pass@host:port/?authSource=admin，漏掉authSource参数会导致MongoDB\Driver\Exception\AuthenticationException - 超时控制靠选项数组：
new MongoDB\Client('mongodb://127.0.0.1', ['connectTimeoutMS' => 5000, 'socketTimeoutMS' => 30000]) - 本地开发默认端口是
27017，不是27018或27019—— 这个错误在 Docker Compose 环境里尤其高频
增删改查必须用 BSON 文档，不能传 JSON 字符串或裸数组
所有操作接口（insertOne、find、updateOne）接收的是 PHP 数组或 BSON 类型对象，不是 JSON 字符串。把 json_encode() 结果直接传进去，会存成字符串字段，而不是结构化文档：
立即学习“PHP免费学习笔记（深入）”；
- 插入时用
$collection->insertOne(['name' => 'Alice', 'age' => 30])，不是insertOne(json_encode([...])) - 按
_id查询必须用MongoDB\BSON\ObjectId：['_id' => new MongoDB\BSON\ObjectId('60a1b2c3d4e5f67890123456')]；传字符串会查不到，因为类型不匹配 - 更新操作第二个参数必须是操作符数组，如
['$set' => ['status' => 'active']]；直接传['status' => 'active']会被当成替换整个文档（等价于$replaceRoot），极大概率误删字段 -
find()返回MongoDB\Driver\Cursor，需遍历或转数组：iterator_to_array($cursor)；直接echo $cursor会报错
字段类型严格，时间、ObjectId、二进制数据不能靠自动转换
MongoDB 不像 MySQL 那样隐式转换类型。PHP 数组里的 'created_at' => time() 会被当整数存，后续用 $gt 查日期范围就失效；同理，字符串 ID 和 ObjectId 在查询时完全不互通：
- 存时间用
MongoDB\BSON\UTCDateTime(strtotime('2025-01-01') * 1000)，不是time()或date('c') - 生成新 ObjectId 应该用
new MongoDB\BSON\ObjectId()，不要手拼 24 位 hex 字符串 - 存布尔值必须用 PHP 的
true/false，不要用字符串'true'—— 后者是字符串类型，$eq: true查不到 - 嵌套文档和数组层级过深（>100 层）或单文档 >16MB 会触发
MongoDB\Driver\Exception\BulkWriteException，这个限制容易在日志聚合场景中突然暴露
最常被跳过的其实是 BSON 类型初始化——比如用 new \MongoDB\BSON\ObjectId() 生成 ID，而不是依赖驱动自动生成；还有把 find([]) 当成“健康检查”来用，却忽略了它实际会触发一次完整网络往返和 cursor 初始化。这些细节不显眼，但一出问题就是线上数据异常或超时雪崩。
