PHP 7 MongoDB 安装与使用全攻略
注意：PHP 7 已于 2022 年正式结束支持（EOL），建议升级到 PHP 8.x 以获得安全更新和性能优化。但如果你必须在 PHP 7（例如 7.4）环境下使用 MongoDB，本指南基于官方文档和社区实践，提供完整步骤。MongoDB PHP 驱动分为 扩展（Extension）（低级 C 实现）和 库（Library）（高层 PHP API），两者结合使用。
一、环境要求
| 组件 | 版本要求 | 说明 |
|---|---|---|
| PHP | 7.0 – 7.4 | 推荐 7.4（最后支持版本） |
| MongoDB 服务器 | ≥ 3.6 | 建议 4.4+ 支持事务 |
| Composer | ≥ 1.0 | 用于安装库 |
| PECL | 已安装 | 用于扩展 |
验证 PHP 版本：
php -v
二、安装 MongoDB 扩展（Extension）
MongoDB 扩展是基础，必须先安装。它提供底层连接支持。
1. Linux (Ubuntu/Debian) 安装
# 更新包源
sudo apt update
# 安装依赖（包括 pkg-config 和 libssl-dev）
sudo apt install php7.4-dev php-pear libssl-dev pkg-config
# 使用 PECL 安装扩展（针对 PHP 7.4，调整版本号）
sudo pecl -d php_suffix=7.4 install mongodb
# 添加到 php.ini（CLI 和 FPM）
echo "extension=mongodb.so" | sudo tee /etc/php/7.4/mods-available/mongodb.ini
sudo phpenmod mongodb
# 重启服务
sudo systemctl restart apache2 # 或 nginx + php7.4-fpm多 PHP 版本：使用
update-alternatives --set php /usr/bin/php7.4切换默认版本。
2. Windows 安装
- 下载 DLL：访问 PECL MongoDB Releases，选择 PHP 7.x 的 x86/x64、非线程安全（NTS）版本（例如
php_mongodb-1.12.0-7.4-nts-vc15-x64.zip）。 - 解压
php_mongodb.dll到 PHP 的ext/目录（例如C:\php7\ext\）。 - 编辑
php.ini（运行php --ini查找路径），添加：
extension=php_mongodb.dll- 重启 Apache/IIS，重启后运行
php -m | grep mongodb验证。
3. macOS 安装
# 使用 Homebrew 安装 PHP 7.4（如果未安装）
brew install php@7.4
# 安装扩展
pecl -d php_suffix=7.4 install mongodb
# 添加到 php.ini
echo "extension=mongodb.so" >> /usr/local/etc/php/7.4/php.ini
# 重启 PHP-FPM
brew services restart php@7.44. 验证安装
php -m | grep mongodb
# 输出：mongodb
# 或创建 test.php
<?php
phpinfo();
?>
# 搜索 "mongodb" 确认模块加载常见错误：
pcre.h not found：安装libpcre3-dev。Unable to load dynamic library：检查 DLL/路径匹配 PHP 版本/架构。- EOL 警告：PHP 7.1/7.2 已不支持新扩展，使用
mongodb-1.6.0等旧版。
三、安装 MongoDB PHP 库（Library）
库提供高层 API（如 CRUD、聚合），通过 Composer 安装。
# 全局安装 Composer（如果未安装）
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
# 在项目目录安装库（兼容 PHP 7）
composer require mongodb/mongodb:^1.12.0 # 选择 PHP 7 兼容版本验证：
composer show mongodb/mongodb四、基本使用示例
1. 连接 MongoDB
<?php
require 'vendor/autoload.php'; // Composer 自动加载
use MongoDB\Client;
// 本地连接
$client = new Client("mongodb://localhost:27017");
// 副本集 + 认证
$client = new Client(
"mongodb://user:pass@host1:27017,host2:27017/mydb?replicaSet=rs0&authSource=admin"
);
// 测试连接
try {
$dbs = $client->listDatabases();
echo "连接成功！数据库列表：\n";
foreach ($dbs as $db) {
echo "- " . $db->getName() . "\n";
}
} catch (Exception $e) {
echo "连接失败：" . $e->getMessage() . "\n";
}
?>2. CRUD 操作
<?php
require 'vendor/autoload.php';
use MongoDB\Client;
use MongoDB\BSON\UTCDateTime;
$client = new Client("mongodb://localhost:27017");
$collection = $client->test->users; // 数据库 test，集合 users
// 插入
$insertResult = $collection->insertOne([
'name' => 'Alice',
'age' => 25,
'tags' => ['php', 'mongodb'],
'created_at' => new UTCDateTime() // UTC 时间戳
]);
echo "插入 ID: " . $insertResult->getInsertedId() . "\n";
// 查询（单个）
$user = $collection->findOne(['name' => 'Alice']);
var_dump($user); // 输出文档
// 查询（多个）+ 排序/分页
$cursor = $collection->find(
['age' => ['$gte' => 18]],
[
'sort' => ['age' => -1], // 降序
'limit' => 5,
'skip' => 0
]
);
foreach ($cursor as $doc) {
echo $doc['name'] . " (年龄: {$doc['age']})\n";
}
// 更新
$collection->updateOne(
['name' => 'Alice'],
['$set' => ['age' => 26]] // 更新年龄
);
// 删除
$collection->deleteOne(['name' => 'Alice']);
?>3. 聚合查询（Aggregation）
<?php
// 按年龄分组统计
$pipeline = [
['$match' => ['age' => ['$gte' => 18]]],
['$group' => [
'_id' => '$tags', // 按标签分组
'count' => ['$sum' => 1]
]],
['$sort' => ['count' => -1]]
];
$results = $collection->aggregate($pipeline);
foreach ($results as $result) {
echo "标签 " . json_encode($result['_id']) . ": {$result['count']} 人\n";
}
?>4. 事务（PHP 7.4+，需副本集）
<?php
$session = $client->startSession();
try {
$session->startTransaction();
$collection->insertOne(['name' => 'TxUser'], ['session' => $session]);
$collection->updateOne(['name' => 'Alice'], ['$inc' => ['age' => 1]], ['session' => $session]);
$session->commitTransaction();
echo "事务成功\n";
} catch (Exception $e) {
$session->abortTransaction();
echo "事务失败: " . $e->getMessage() . "\n";
} finally {
$session->endSession();
}
?>五、性能优化与最佳实践
| 优化 | 说明 |
|---|---|
| 连接池 | 在 Client 构造器中设置 'maxConnections' => 50 |
| 索引 | $collection->createIndex(['name' => 1]) |
| 批量操作 | 使用 insertMany() 或 bulkWrite() |
| 投影 | find($filter, ['projection' => ['name' => 1]]) 只返回字段 |
| 错误处理 | 始终用 try-catch 包裹操作 |
调试：启用
ini_set('mongodb.debug', 'stderr');查看底层命令。
六、常见问题排查
| 问题 | 解决方案 |
|---|---|
extension not loaded | 检查 php.ini 和重启服务；运行 php -i | grep mongodb |
Authentication failed | 确保 URI 中有 &authSource=admin |
Composer 依赖冲突 | 指定旧版：^1.12.0 |
pcre.h not found (编译时) | sudo apt install libpcre3-dev |
| PHP 7 EOL | 计划升级；旧版扩展如 mongodb-1.6.0 仅限安全修复 |
七、学习资源
- 官方扩展安装：PHP.net MongoDB Installation
- 官方库教程：MongoDB PHP Library
- 社区讨论：Stack Overflow PHP 7 MongoDB
- 示例代码：GitHub MongoDB PHP Library
下一步：运行上述示例测试连接。如果你遇到具体错误（如 OS 版本），提供更多细节，我可以给出针对性脚本！
