phpEnv配置MongoDB教程 phpEnv连接MongoDB数据库-php教程-PHP中文网

php 连 mongodb 必须安装 mongodb 扩展（非已废弃的 mongo），启用后 uri 需含 ?retrywrites=true，find() 返回游标须遍历或调 toarray()，_id 必须用 objectid 实例确保类型一致。

phpenv配置mongodb教程 phpenv连接mongodb数据库

PHP 环境要连上 MongoDB，核心就一条：必须装对扩展（mongodb），不是 mongo，后者在 PHP 7.0+ 已彻底移除，装了也白装。

很多连接失败根本不是代码问题，而是扩展压根没装对或没启用：

运行 php -m | grep mongodb（Linux/macOS）或查看 phpinfo() 页面里有没有 mongodb 模块 —— 如果只看到 mongo 或啥都没有，立刻停手排查
Class 'MongoDB\Client' not found 或 Class 'MongoDB\Driver\Manager' not found 都是扩展未加载的明确信号
Ubuntu/Debian 用户别只装 php-mongodb 包，还得检查 php.ini 是否真启用了 extension=mongodb.so（有时包安装后这行被注释了）
Windows 用户务必匹配 PHP 版本（如 8.2）、线程安全标识（TS/NTS）和 VC 编译器版本，错一个就 dl() failed

这是 PHP 8.1+ 和现代 MongoDB 驱动（4.0+）的硬性要求，漏掉会导致连接看似成功、写操作却静默失败：

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

最简本地连接也得写成：new MongoDB\Client('mongodb://localhost:27017/?retryWrites=true')
带认证时，retryWrites=true 必须放在查询参数末尾，例如：mongodb://user:pass@localhost:27017/mydb?retryWrites=true
密码含 /、@、: 等字符？必须先用 urlencode() 处理，否则解析 URI 会出错
连 MongoDB Atlas？至少补全 ?ssl=true&retryWrites=true&w=majority，少一个都可能卡在 handshake 阶段

新手最常踩的坑：直接 var_dump($collection->find([]))，结果只看到 object(MongoDB\Driver\Cursor)#5，以为没查到数据：

要遍历输出：foreach ($collection->find(['status' => 'active']) as $doc) { echo $doc['name']; }
要转成数组（仅限小结果集）：$collection->find([])->toArray()
想取前 5 条？传选项：$collection->find([], ['limit' => 5])，别用 array_slice() 在 PHP 层截取
游标不调用 toArray() 或遍历，底层连接不会真正发起请求 —— 这是 lazy connect 机制，但错误处理也延迟到这时才抛异常

如果手动设 _id 为字符串（比如 '_id' => 'abc123'），MongoDB 会照存，但后续用 ObjectId 查询就查不到：

插入时让驱动自动生成：$collection->insertOne(['name' => 'Alice']) → 返回的 InsertOneResult 里有 getInsertedId()
手动指定 ObjectId：new MongoDB\BSON\ObjectId('507f1f77bcf86cd799439011')，字符串必须是 24 位十六进制
查询时也得用同类型：$collection->findOne(['_id' => new MongoDB\BSON\ObjectId('...')])
从 JSON 解析来的 _id 字符串，必须显式转换，否则类型不匹配，查不到

真正难的不是写几行连接代码，而是所有隐式约定：URI 参数缺一不可、游标必须消费、_id 类型必须严格一致、扩展名不能拼错 —— 这些地方错一个，错误现象都模棱两可，排查起来比语法错误更费时间。