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 ：提供源代码、免费使用且可自行管理的 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. 下载Community或Enterprise版本的 MongoDB Server。

2. 安装和配置MongoDB Server。

3. 启动该服务器。

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

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

如果需要指定不同的主机名或 IP 地址，请参阅我们的《服务器手册》中有关连接字符串的条目。

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

兼容性

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

另请参阅

• PHP 库、框架和工具