PHP操作MongoDB必须使用官方mongodb扩展（非废弃的mongo扩展），通过MongoDB\Client连接，基于BSON文档进行增删改查，连接惰性触发，需注意ObjectId、DateTime等类型正确使用及字段类型严格性。
PHP 操作 MongoDB 不再用
扩展（已废弃），必须用
扩展（官方维护，基于 libmongoc）。它不提供传统“连接-查询-关闭”式 API，而是以面向对象 + BSON 文档为核心，直接对接现代 MongoDB 协议（4.0+）。
怎么确认已正确安装 mongodb 扩展
运行
，有输出说明扩展已加载；若报错或无输出，需手动安装：
Linux（pecl）：
，然后在
中加
macOS（Homebrew +
php
）：
，检查
显示的配置路径是否包含该扩展
Windows：从
pecl.php.net
下载对应 PHP 版本和线程安全（TS/NTS）的
，放入
并在
中添加
验证是否生效：
应返回
连接 MongoDB 并选择数据库/集合
是底层连接管理器，但日常操作推荐用官方高阶库
（Composer 安装），它封装了
、
和 BSON 类型处理：
安装客户端库：
连接示例：
注意：连接字符串中不能省略
前缀；本地默认端口是
，非
或其他
连接本身不触发网络请求（lazy connect），首次操作（如
）才真正建连；超时、认证失败等错误会在首次操作时抛出
等
插入、查询、更新文档的典型写法
所有操作都基于
文档（PHP 数组或
等类型），不接受 JSON 字符串直接传入：
PHP 8.5.5
PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。
下载
立即学习
“
PHP免费学习笔记（深入）
”；
插入单条：
，返回
，可用
获取
查询全部：
返回
，需遍历：
更新单条：
；注意第二个参数必须是操作符（如
、
），不能直接传数组
查询条件中用
匹配
：
，字符串 ID 不能直接当数组键用
常见报错和绕不开的坑
这些错误高频出现，且原因隐蔽：
：连接字符串格式错（比如漏了
）、MongoDB 进程没启、防火墙拦截、或 DNS 解析失败（尤其用
时建议换
）
：把
当数组访问了，正确取值是
插入后查不到：未指定
时驱动自动生成
，但如果你用字符串 ID 插入（如
），后续用
查不到——因为不是同类型
日期存成字符串而非
：用
而不是
，否则 MongoDB 当普通字符串存，无法做时间范围查询
最易被忽略的是：所有文档操作都默认不校验字段类型，
和
的
在 MongoDB 里是完全不同的值，业务逻辑里混用会导致查不到数据，却不会报错。
mongomongodbphp -m | grep mongodbpecl install mongodbphp.iniextension=mongodb.sopecl install mongodbphp --iniphp_mongodb.dllext/php.iniextension=php_mongodb.dllphp -r "var_dump(extension_loaded('mongodb'));"bool(true)MongoDB\Driver\Managermongodb/mongodbManagerCollectioncomposer require mongodb/mongodb$client = new MongoDB\Client('mongodb://127.0.0.1:27017');
$collection = $client->selectDatabase('test')->selectCollection('users');mongodb://2701727018find()MongoDB\Driver\Exception\ConnectionTimeoutExceptionBSONMongoDB\BSON\ObjectId$collection->insertOne(['name' => 'Alice', 'age' => 30])InsertOneResultgetInsertedId()_id$collection->find([])Cursorforeach ($collection->find(['age' => ['$gt' => 25]]) as $doc) {
echo $doc['name'] . "\n";
}$collection->updateOne(['name' => 'Alice'], ['$set' => ['age' => 31]])$set$incMongoDB\BSON\ObjectId_id['_id' => new MongoDB\BSON\ObjectId('60a1b2c3d4e5f67890123456')]Uncaught MongoDB\Driver\Exception\RuntimeException: No servers foundmongodb://localhost127.0.0.1Cannot use object of type MongoDB\BSON\ObjectId as arrayObjectId$id->__toString()_idObjectId['_id' => 'abc']new ObjectId('abc')DateTimeInterfacenew DateTime()date('Y-m-d')intstring1