PHP7 集成 MongoDB 扩展及新版 API 操作指南

准备环境与编译安装

PHP7 引入了一套全新的 MongoDB 驱动程序（mongodb extension），旧的 mongo.so 已停止维护。新扩展仅支持 MongoDB 2.6.x 及以上版本。在安装前，需确保系统已安装必要的依赖库，并根据实际的 PHP 路径配置编译参数。

第1步：安装依赖库

为了成功编译 MongoDB C 客户端库，需要安装 openldap-devel 等系统依赖。以 CentOS/RHEL 环境为例：

yum -y install openldap-devel

第2步：下载扩展源码

访问 PECL 官网获取稳定的 MongoDB 扩展包。建议下载适用于 PHP7 的最新稳定版（如 1.1.1 或更高版本）：

wget https://pecl.php.net/get/mongodb-1.1.1.tgz
tar -zxvf mongodb-1.1.1.tgz
cd mongodb-1.1.1

第3步：编译并安装扩展

使用 phpize 构建编译环境，并通过 --with-php-config 指向当前 PHP7 的安装目录。执行编译并安装生成的 .so 文件：

/home/server/php7/bin/phpize
./configure --with-php-config=/home/server/php7/bin/php-config
make && make install

编译成功后，mongodb.so 文件将位于类似 lib/php/extensions/no-debug-non-zts-20151012/ 的目录下。

第4步：配置 php.ini

打开 PHP 配置文件 php.ini，添加以下行以加载扩展：

extension=mongodb.so

重启 Web 服务器或 PHP-FPM 服务使配置生效。

MongoDB 连接初始化

使用新版 API 时，首先需要实例化 MongoDB\Driver\Manager 对象来管理连接池和集群信息。

<?php
$manager = new MongoDB\Driver\Manager("mongodb://127.0.0.1:27017");
var_dump($manager);
?
>

输出结果显示了连接的 URI、集群状态（state）、请求 ID 以及各种超时设置。此时连接尚未建立物理通道，仅在首次执行写操作或查询时才进行握手。

执行批量写入操作 (BulkWrite)

对于需要插入、更新或删除大量数据的场景，使用 BulkWrite 可以显著减少网络往返次数。以下是包含混合操作的完整示例，包括错误处理和写入关注点（Write Concern）的设置。

<?php
$bulk = new MongoDB\Driver\BulkWrite(['ordered' => true]);

// 定义一系列操作
$bulk->delete([]); // 警告：此操作可能清空集合，请谨慎使用
$bulk->insert(['_id' => 1]);
$bulk->insert(['_id' => 2]);
$bulk->insert(['_id' => 3, 'hello' => 'world']);

$bulk->update(['_id' => 3], ['$set' => ['hello' => 'earth']]);
$bulk->insert(['_id' => 4, 'hello' => 'pluto']);
$bulk->update(['_id' => 4], ['$set' => ['hello' => 'moon']]);

// 故意插入重复 _id 以测试 ordered bulk 的行为
$bulk->insert(['_id' => 3]); 
$bulk->insert(['_id' => 4]);
$bulk->insert(['_id' => 5]);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
// 设置写入关注点为多数派确认，最大等待时间1000ms
$writeConcern = new MongoDB\Driver\WriteConcern(
    MongoDB\Driver\WriteConcern::MAJORITY, 1000
);

try {
    $result = $manager->executeBulkWrite('db.collection', $bulk, $writeConcern);
} catch (MongoDB\Driver\Exception\BulkWriteException $e) {
    $result = $e->getWriteResult();
    
    // 检查是否满足写入关注点
    if ($writeConcernError = $result->getWriteConcernError()) {
        printf("Write Concern Error (%d): %s\n",
            $writeConcernError->getCode(),
            $writeConcernError->getMessage()
        );
    }
    
    // 遍历具体的写操作错误
    foreach ($result->getWriteErrors() as $writeError) {
        printf("Operation #%d: %s (%d)\n",
            $writeError->getIndex(),
            $writeError->getMessage(),
            $writeError->getCode()
        );
    }
} catch (MongoDB\Driver\Exception\Exception $e) {
    printf("Other error: %s\n", $e->getMessage());
    exit;
}

printf("Inserted %d document(s)\n", $result->getInsertedCount());
printf("Updated %d document(s)\n", $result->getModifiedCount());
?
>

• ordered=true：表示按顺序执行，若中途发生错误，后续操作将不再执行。
• WriteConcern：控制数据持久化的可靠性，MAJORITY 要求多数节点同步完成才返回确认。

执行查询操作

使用 MongoDB\Driver\Query 构造查询对象，配合 ReadPreference 指定读取偏好（如主节点读取），最后通过 executeQuery 获取游标。

<?php
$filter = [];
$options = [
    // 投影：仅返回 title 和 article 字段
    "projection" => ["title" => 1, "article" => 1],
    // 排序：views 降序
    "sort" => ["views" => -1],
    // 修饰符
    "modifiers" => [
        '$comment' => "This is a query comment",
        '$maxTimeMS' => 100
    ]
];

$query = new MongoDB\Driver\Query($filter, $options);
$manager = new MongoDB\Driver\Manager("mongodb://localhost:27017");

// 设置为只读主节点
$readPreference = new MongoDB\Driver\ReadPreference(
    MongoDB\Driver\ReadPreference::RP_PRIMARY
);

// 执行查询，注意集合名称格式为 dbName.collectionName
$cursor = $manager->executeQuery(
    "databaseName.collectionName", 
    $query, 
    $readPreference
);

foreach ($cursor as $document) {
    var_dump($document);
}
?
>

上述代码展示了如何设置字段投影、排序规则以及查询超时限制。遍历 $cursor 即可逐条获取文档对象。

注意事项与排错

• 命名空间差异：PHP7 新版 API 严格区分大小写且使用反斜杠分隔命名空间，如 MongoDB\Driver\Manager，切勿写成 MongoDB/Driver/Manager 或使用旧的 MongoClient。
• 空删除风险：代码示例中 $bulk->delete([]) 若无过滤条件将删除整个集合的数据，生产环境中务必确保过滤条件准确。
• 依赖版本：确保 MongoDB 服务端版本不低于 2.6.x，否则新版驱动的部分功能可能不可用。

以上就是 PHP7 集成 MongoDB 扩展及新版 API 使用的详细内容，更多关于 PHP 数据库开发与 MongoDB 优化的资料请关注本站其它相关文章！