MongoDB PHP 驱动程序

简介

欢迎访问官方 MongoDB PHP 驱动程序的文档站点。您可以将该驱动程序添加到应用程序中，以便在 PHP 中使用 MongoDB。MongoDB PHP 驱动程序由以下组件组成：

• 扩展，它提供了一个底层 API，主要用于将 libmongoc 和 libbson 与 PHP 集成。

• 该库提供了一个高级 API，它可用于处理与其他 MongoDB 语言驱动程序一致的 MongoDB 数据库。

虽然可以单独使用扩展，但 MongoDB 建议同时使用扩展和库。要了解有关 PHP 驱动程序组件的更多信息，请参阅本页的驱动程序架构部分。

浏览以下链接以了解有关驱动程序的更多信息，并访问有关设置可运行的项目的教程内容：

• Tutorials

• 扩展架构和内部结构

• 文档

  • 库

  • 扩展

• 变更日志

  • 库

  • 扩展

• 源代码

  • 库

  • 扩展

驱动程序架构

本节介绍 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

安装 PHP 库的首选方法是使用 Composer，具体步骤是在项目根目录下运行以下命令：

$ composer require mongodb/mongodb

安装该库后，请确保应用程序包含 Composer 的自动加载器，如下例所示：

<?php
require_once __DIR__ . '/vendor/autoload.php';

其他安装说明可在库文档中找到。

连接到 MongoDB Atlas

您可以使用以下连接片段来测试与 Atlas 上 MongoDB 部署的连接：

<?php
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”。

在没有 Stable API 的情况下连接到 MongoDB Atlas

如果您使用的 MongoDB 版本或驱动程序不支持“稳定 API”功能，您可以使用以下代码片段来测试与 Atlas 上的 MongoDB 部署的连接：

<?php
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 集群，则需完成以下操作：

1. 下载 MongoDB Server Community 或 Enterprise 版本。

2. 安装并配置 MongoDB Server。

3. 启动该服务器。

在成功启动 MongoDB 服务器后，在驱动程序连接代码中指定连接字符串。

如果 MongoDB Server 在本地运行，您可以使用连接字符串 "mongodb://localhost:<port>"，其中 <port> 是您配置服务器以侦听传入连接的端口号。

如果您需要指定不同的主机名或 IP 地址，请参阅 Server 手册中有关连接字符串的条目。

要测试是否能够连接到服务器，请替换连接到 MongoDB Atlas 示例代码中的连接字符串，并运行此代码。

兼容性

由于在 32 位平台上表示 64 位整数可能存在问题，建议用户使用 64 位环境。使用 32 位平台时，请注意，从数据库读取的任何 64 位整数都将作为 MongoDB\BSON\Int64 实例返回，而不是 PHP 整数类型。

另请参阅

• PHP 库、框架和工具