云数据库 MongoDB PHP SDK

操作场景
PHP 广泛应用于 Web 应用开发，MongoDB PHP Library 在底层 mongodb 扩展基础上提供了简洁的面向对象 API。本文提供使用 PHP 连接云数据库 MongoDB 的完整示例，覆盖底层扩展和高层库两种接入方式。
前提条件
已创建云数据库 MongoDB 实例，且实例状态为运行中。
已准备一台与 MongoDB 实例在同一 VPC 内的云服务器 CVM，且已安装 PHP 7.4 或以上版本。
驱动安装
PHP 连接 MongoDB 需要安装两个组件：
组件
类型
说明
mongodb 扩展
PHP C 扩展（底层）
提供底层 BSON 和网络通信能力
mongodb/mongodb 库
Composer 包（上层，推荐）
基于底层扩展封装的面向对象 API
安装底层扩展：
pecl install mongodb
安装完成后，在 php.ini 中添加：
extension=mongodb.so
安装上层库：
composer require mongodb/mongodb
方式一：使用 MongoDB PHP Library（推荐）
MongoDB PHP Library 提供了简洁的面向对象 API，是推荐的使用方式。
<?php
require_once __DIR__ . '/vendor/autoload.php';
﻿
use MongoDB\\Client;
use MongoDB\\Exception\\RuntimeException;
﻿
// 连接 URI（请替换为您的实际连接信息）
$uri = 'mongodb://mongouser:thepasswordA1@10.66.187.127:27017/admin';
﻿
try {
    // 创建客户端连接
    $client = new Client($uri, [
        'retryWrites' => true,
        'w'           => 'majority',
    ], [
        'typeMap' => [
            'root'     => 'array',
            'document' => 'array',
            'array'    => 'array',
        ],
    ]);
﻿
    // 选择数据库和集合
    $collection = $client->mydb->users;
﻿
    // ========== 插入文档 ==========
    $result = $collection->insertOne([
        'username'  => 'jack',
        'age'       => 31,
        'email'     => 'jack@example.com',
        'createdAt' => new MongoDB\\BSON\\UTCDateTime(),
    ]);
    printf("插入文档 ID: %s\\n", $result->getInsertedId());
﻿
    // 批量插入
    $result = $collection->insertMany([
        ['username' => 'alice', 'age' => 28, 'email' => 'alice@example.com'],
        ['username' => 'bob',   'age' => 35, 'email' => 'bob@example.com'],
    ]);
    printf("批量插入 %d 条文档\\n", $result->getInsertedCount());
﻿
    // ========== 查询文档 ==========
    $user = $collection->findOne(['username' => 'jack']);
    printf("查询单条: %s\\n", json_encode($user, JSON_UNESCAPED_UNICODE));
﻿
    // 条件查询（年龄大于 30）
    $cursor = $collection->find(['age' => ['$gt' => 30]]);
    echo "年龄大于 30 的用户:\\n";
    foreach ($cursor as $doc) {
        printf("  - %s, 年龄: %d\\n", $doc['username'], $doc['age']);
    }
﻿
    // ========== 更新文档 ==========
    $result = $collection->updateOne(
        ['username' => 'jack'],
        ['$set' => ['age' => 32]]
    );
    printf("更新 %d 条文档\\n", $result->getModifiedCount());
﻿
    // ========== 删除文档 ==========
    $result = $collection->deleteMany([
        'username' => ['$in' => ['jack', 'alice', 'bob']]
    ]);
    printf("删除 %d 条文档\\n", $result->getDeletedCount());
﻿
} catch (RuntimeException $e) {
    printf("操作失败: %s\\n", $e->getMessage());
}
运行输出示例：
插入文档 ID: 6789abcdef1234567890abcd
批量插入 2 条文档
查询单条: {"_id":"6789abcdef1234567890abcd","username":"jack","age":31,"email":"jack@example.com"}
年龄大于 30 的用户:
  - jack, 年龄: 31
  - bob, 年龄: 35
更新 1 条文档
删除 3 条文档
方式二：使用底层 mongodb 扩展
如果项目未使用 Composer，可直接使用底层 MongoDB\\Driver API：
<?php
// 连接 URI
$uri = 'mongodb://mongouser:thepasswordA1@10.66.187.127:27017/admin';
$manager = new MongoDB\\Driver\\Manager($uri);
﻿
// ========== 写入数据 ==========
$bulk = new MongoDB\\Driver\\BulkWrite;
$bulk->insert([
    'username'  => 'jack',
    'age'       => 31,
    'email'     => 'jack@example.com',
]);
﻿
// 写入到 mydb.users 集合
$writeConcern = new MongoDB\\Driver\\WriteConcern(MongoDB\\Driver\\WriteConcern::MAJORITY, 1000);
$result = $manager->executeBulkWrite('mydb.users', $bulk, $writeConcern);
printf("插入 %d 条文档\\n", $result->getInsertedCount());
﻿
// ========== 查询数据 ==========
$filter = ['username' => 'jack'];
$options = ['sort' => ['age' => -1]];
$query = new MongoDB\\Driver\\Query($filter, $options);
$rows = $manager->executeQuery('mydb.users', $query);
﻿
foreach ($rows as $row) {
    print_r($row);
}
注意事项
推荐使用上层库：mongodb/mongodb Composer 包提供了更友好的 API，新项目建议优先使用。
PHP 版本：MongoDB PHP Library 1.17及以上版本要求 PHP 7.4 或更高。
连接复用：在 PHP-FPM 环境下，MongoDB\\Client 实例会在请求结束后自动释放。在常驻进程（如 Swoole）中使用时，应注意连接池管理。
BSON 类型：PHP 中的 MongoDB 日期类型使用 MongoDB\\BSON\\UTCDateTime，而非 PHP 原生 DateTime。查询结果中的 _id 为 MongoDB\\BSON\\ObjectId 类型。
常见问题
连接时提示 "Authentication failed"
错误信息示例：
MongoDB\\Driver\\Exception\\AuthenticationException: Authentication failed.
请按以下步骤排查：
1. 确认 URI 中指定了认证库 admin。
// 正确：URI 路径为 /admin
$uri = 'mongodb://mongouser:thepasswordA1@10.66.187.127:27017/admin';
// 正确：连接业务库时通过 authSource 指定认证库
$uri = 'mongodb://mongouser:thepasswordA1@10.66.187.127:27017/mydb?authSource=admin';
﻿
// 错误：连接业务库时未指定 authSource，驱动将默认以 mydb 库认证，导致认证失败
$uri = 'mongodb://mongouser:thepasswordA1@10.66.187.127:27017/mydb';
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: PHP 8.3.6 (cli) (built: Jul 14 2025 18:30:55) (NTS)
2. 确认密码中的特殊字符已进行 URL 编码：使用 rawurlencode() 对密码进行编码。
$password = rawurlencode('pass@123'); // 输出: pass%40123
$uri = sprintf('mongodb://mongouser:%s@10.66.187.127:27017/admin', $password);
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: PHP 8.3.6 (cli) (built: Jul 14 2025 18:30:55) (NTS)
3. 确认用户名和密码正确：登录 MongoDB 控制台，在实例管理页面确认用户信息。如忘记密码，可在控制台重置。
提示 "Class 'MongoDB\\Client' not found"
错误信息示例：
PHP Fatal error: Uncaught Error: Class 'MongoDB\\Client' not found in /path/to/script.php
该错误表示 MongoDB PHP Library 未正确安装或未加载。请按以下步骤排查：
1. 确认底层 mongodb 扩展已安装：执行以下命令，确认扩展已加载：
php -m | grep mongodb
如输出 mongodb，说明扩展已安装。
如无输出，请安装扩展：
pecl install mongodb
安装完成后，在 php.ini 中添加：
extension=mongodb.so
2. 确认 Composer 包已安装。执行以下命令，确认 mongodb/mongodb 包已安装：
composer show mongodb/mongodb
如未安装，请执行：
composer require mongodb/mongodb
3. 确认 autoload.php 已引入：在 PHP 脚本中，确认文件顶部包含 Composer 自动加载文件：
<?php
require_once __DIR__ . '/vendor/autoload.php';
提示 "No suitable servers found" 或连接超时
错误信息示例：
MongoDB\\Driver\\Exception\\ConnectionTimeoutException: No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling hello on '10.66.187.127:27017']
请按以下步骤排查：
1. 确认网络连通性：在 CVM 上执行以下命令，验证网络是否可达：
telnet <MongoDB实例IP> 27017
输出 Connected 表示网络可达，请检查认证配置。
输出 Connection timed out 或 Connection refused 表示网络不通，请确认 CVM 与 MongoDB 实例在同一 VPC 内，并检查安全组规则。
2. 检查 PHP-FPM 或 CLI 环境差异：PHP-FPM 和 CLI 可能使用不同的 php.ini 配置文件。请分别确认两个环境下 mongodb 扩展均已加载：
# 查看 CLI 环境的 php.ini 路径
php --ini
﻿
# 查看 PHP-FPM 环境的配置（通过 phpinfo()）
php -r "phpinfo();" | grep "Loaded Configuration File"
组件	类型	说明
`mongodb` 扩展	PHP C 扩展（底层）	提供底层 BSON 和网络通信能力
`mongodb/mongodb` 库	Composer 包（上层，推荐）	基于底层扩展封装的面向对象 API
PHP SDK

本页目录：

操作场景

前提条件

驱动安装

方式一：使用 MongoDB PHP Library（推荐）

方式二：使用底层 mongodb 扩展

注意事项

常见问题

连接时提示 "Authentication failed"

Running Environment

Running Environment

提示 "Class 'MongoDB\\Client' not found"

提示 "No suitable servers found" 或连接超时
