MongoDB PHP 驱动程序
在此页面上
简介
欢迎访问官方 MongoDB PHP 驱动程序的文档站点。您可以将该驱动程序添加到应用程序中,以便在 PHP 中使用 MongoDB。MongoDB PHP 驱动程序由以下组件组成:
扩展,它提供了一个底层 API,主要用于将 libmongoc 和 libbson 与 PHP 集成。
该库提供了一个高级 API,它可用于处理与其他 MongoDB 语言驱动程序一致的 MongoDB 数据库。
虽然可以单独使用扩展,但 MongoDB 建议同时使用扩展和库。要了解有关 PHP 驱动程序组件的更多信息,请参阅本页的驱动程序架构部分。
浏览以下链接以了解有关驱动程序的更多信息,并访问有关设置可运行的项目的教程内容:
驱动程序架构
本节介绍 PHP 驱动程序的各个组件是如何协同工作的。这些组件分为以下一般类别:
高级 API,其中包括库和其他集成
扩展,包括集成各种系统库的扩展
系统,包括 C 驱动程序、BSON 库和加密库
下图说明了 PHP 驱动程序组件的架构:
PHP 库提供了与其他 MongoDB 驱动程序一致的 API。该库会不断更新,以满足跨驱动程序规范。必须将该库添加为依赖项才能在大多数 PHP 应用程序中访问 MongoDB。
该扩展使用 PECL 分发,并将 PHP 连接至系统库。该扩展的公共 API 可提供以下功能:
连接管理
BSON 编码和解码
对象文档序列化
命令执行
游标管理
要了解有关系统库的更多信息,请参阅 C 驱动程序文档。
连接到兼容的 MongoDB 部署
您可以使用 PHP Driver 连接到以下环境中托管的部署:
MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务
MongoDB Enterprise:基于订阅、自行管理的 MongoDB 版本
MongoDB Community:source-available、免费使用且可自行管理的 MongoDB 版本
安装
首先,确保您的系统上已安装最新版本的 PHP。有关下载和安装说明,请参阅官方 PHP 手册。
在安装适用于 MongoDB 的 PHP 库之前,请先安装 PHP MongoDB 扩展。您可以在命令行上使用 PECL 安装该扩展:
sudo pecl install mongodb
最后,将以下行添加到 php.ini
文件中:
extension=mongodb.so
注意
在某些系统上,单个 SAPI 可能有多个 INI 文件(例如CLI、FPM)。确保在您需要的所有 SAPI 中启用扩展。
安装 PHP 库的首选方法是使用 Composer,具体步骤是在项目根目录下运行以下命令:
composer require mongodb/mongodb
安装该库后,请确保应用程序包含 Composer 的自动加载器,如下例所示:
require_once __DIR__ . '/vendor/autoload.php';
其他安装说明可在库文档中找到。
连接到 MongoDB Atlas
您可以使用以下连接片段来测试与 Atlas 上 MongoDB 部署的连接:
use Exception; use MongoDB\Client; use MongoDB\Driver\ServerApi; // Replace the placeholder with your Atlas connection string $uri = '<connection string>'; // Specify Stable API version 1 $apiVersion = new ServerApi(ServerApi::V1); // Create a new client and connect to the server $client = new MongoDB\Client($uri, [], ['serverApi' => $apiVersion]); try { // Send a ping to confirm a successful connection $client->selectDatabase('admin')->command(['ping' => 1]); echo "Pinged your deployment. You successfully connected to MongoDB!\n"; } catch (Exception $e) { printf($e->getMessage()); }
此连接代码段使用 Stable API 功能,可以在使用 PHP 驱动程序 v1.9 及更高版本连接到 MongoDB Server v5.0 及更高版本时启用该功能。使用此功能时,可以更新驱动程序或服务器,而不必担心 Stable API 涵盖的任何命令的向后兼容性问题。
如需了解有关“Stable API”功能的更多信息,请参阅“服务器”手册中的“Stable API”。
注意
从 2022 年 2 月开始,版本化 API被称为 Stable API。此次命名更改后,所有概念和功能均保持不变。
在没有 Stable API 的情况下连接到 MongoDB Atlas
如果您使用的 MongoDB 版本或驱动程序不支持“稳定 API”功能,您可以使用以下代码片段来测试与 Atlas 上的 MongoDB 部署的连接:
use Exception; use MongoDB\Client; // Replace the placeholder with your Atlas connection string $uri = '<connection string>'; // Create a new client and connect to the server $client = new MongoDB\Client($uri); try { // Send a ping to confirm a successful connection $client->selectDatabase('admin')->command(['ping' => 1]); echo "Pinged your deployment. You successfully connected to MongoDB!\n"; } catch (Exception $e) { printf($e->getMessage()); }
连接到本地计算机上的 MongoDB Server
如果您需在本地机器上运行 MongoDB 服务器以用于开发目的而不是使用 Atlas 集群,则需完成以下操作:
下载 MongoDB Server Community 或 Enterprise 版本。
安装并配置 MongoDB Server。
启动该服务器。
重要
务必保护您的 MongoDB 服务器免受恶意攻击。请参阅我们的安全检查清单,获取安全建议清单。
在成功启动 MongoDB 服务器后,在驱动程序连接代码中指定连接字符串。
如果 MongoDB Server 在本地运行,您可以使用连接字符串 "mongodb://localhost:<port>"
,其中 <port>
是您配置服务器以侦听传入连接的端口号。
如果您需要指定不同的主机名或 IP 地址,请参阅 Server 手册中有关连接字符串的条目。
要测试是否能够连接到服务器,请替换连接到 MongoDB Atlas 示例代码中的连接字符串,并运行此代码。
兼容性
由于在 32 位平台上表示 64 位整数可能存在问题,建议用户使用 64 位环境。使用 32 位平台时,请注意,从数据库读取的任何 64 位整数都将作为 MongoDB\BSON\Int64 实例返回,而不是 PHP 整数类型。
MongoDB 兼容性
以下兼容性表格指定了与特定版本的 MongoDB 一起使用的推荐版本或 PHP 驱动程序版本。
第一列列出驱动程序版本。
重要
在服务器版本生命周期结束 (EOL) 日期之后的三年内,MongoDB 将确保 MongoDB Server 与驱动程序兼容。要了解有关 MongoDB 版本和 EOL 日期的更多信息,请参阅 MongoDB 软件生命周期时间表。
兼容性表图例
Icon | 解释 |
---|---|
✓ | 支持所有功能。 |
⊛ | 该驱动程序版本将与 MongoDB 版本一起使用,但并不支持所有新的 MongoDB 功能。 |
无标记 | 驱动程序版本未使用 MongoDB 版本测试。 |
PHP 驱动程序版本 | MongoDB 8.0 | MongoDB 7.0 | MongoDB 6.0 | MongoDB 5.0 | MongoDB 4.4 | MongoDB 4.2 | MongoDB 4.0 | MongoDB 3.6 | MongoDB 3.4 | MongoDB 3.2 | MongoDB 3.0 | MongoDB 2.6 |
---|---|---|---|---|---|---|---|---|---|---|---|---|
ext + lib 1 。 20 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||||
ext + lib 1.16 至 1.19 | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||
ext + lib 1.15[1] | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||
ext 1.14 + lib 1.13 | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||
扩展 1.13 + 库 1.12 | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||
ext 1.12 + lib 1.11 | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.11 + lib 1.10 | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.10 + lib 1.9 | ⊛ | ⊛ | ⊛ | ✓ [2] | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.9 + lib 1.8 | ⊛ | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.8 + lib 1.7 | ⊛ | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.7 + lib 1.6 | ⊛ | ⊛ | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.6 + lib 1.5 | ⊛ | ⊛ | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.5 + lib 1.4 | ⊛ | ⊛ | ⊛ | ⊛ | ⊛ | ⊛ | ✓ | ✓ | ✓ | ✓ | ✓ | |
ext 1.4 + lib 1.3 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.3 + lib 1.2 | ✓ | ✓ | ✓ | ✓ | ||||||||
ext 1.2 + lib 1.1 | ✓ | ✓ | ✓ | ✓ | ||||||||
ext 1.1 + lib 1.0 | ✓ | ✓ | ✓ | |||||||||
ext 1.0 | ✓ | ✓ |
[1] | (1, 2) 已跳过 MongoDB PHP 库的 1.14 版本,恢复库和扩展之间的版本奇偶校验。 |
[2] | 扩展 1.10 + 库 1.9 驱动程序不支持从节点上的快照读取。有关详细信息,请参阅 MongoDB Server 版本 5.0 发布说明。 |
语言兼容性
以下兼容性表格指定了与特定版本的 PHP 一起使用的推荐版本或 PHP 驱动程序版本。
第一列列出了驱动程序版本。
PHP 驱动程序版本 | PHP 8.4 | PHP 8.3 | PHP 8.2 | PHP 8.1 | PHP 8.0 | PHP 7.4 | PHP 7.3 | PHP 7.2 | PHP 7.1 | PHP 7.0 | PHP 5.6 | PHP 5.5 |
---|---|---|---|---|---|---|---|---|---|---|---|---|
ext + lib 1 。 20 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||||
ext + lib 1.17 至 1.19 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext + lib 1.16 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||||
ext + lib 1.15[1] | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | |||||
ext 1.14 + lib 1.13 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
扩展 1.13 + 库 1.12 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.12 + lib 1.11 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.11 + lib 1.10 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.10 + lib 1.9 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.9 + lib 1.8 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||||
ext 1.8 + lib 1.7 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.7 + lib 1.6 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||||
ext 1.6 + lib 1.5 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||||
ext 1.5 + lib 1.4 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ||||||
ext 1.4 + lib 1.3 | ✓ | ✓ | ✓ | ✓ | ✓ | |||||||
ext 1.3 + lib 1.2 | ✓ | ✓ | ✓ | ✓ | ✓ |
有关如何阅读兼容性表的更多信息,请参阅我们的 MongoDB 兼容性表指南。
如何获得帮助
在我们的 MongoDB Community 论坛上提问。
访问我们的支持渠道。