/ /

PHP库

连接

Docs 主页

客户端库

PHP

PHP库

连接

指定连接选项

Overview

本页介绍了PHP库中提供的MongoDB连接和身份验证选项。

设置连接选项

您可以通过在连接 URI 中指定选项或将选项传递给MongoDB\Client构造函数来配置连接。

使用连接 URI

如果将连接 URI 传递给MongoDB\Client构造函数，则可以将连接选项作为<name>=<value>对包含在 URI 中。在以下示例中，连接 URI 将tls选项设置为true ，并将tlsCertificateKeyFile选项设置为/path/to/file.pem ：

// Replace the placeholders with your actual hostname, port, and path to the certificate key file
$uri = 'mongodb://<hostname>:<port>/?tls=true&tlsCertificateKeyFile=/path/to/file.pem';
// Create a MongoDB client
$client = new MongoDB\Client($uri);

使用MongoDB\Client 对象

您可以将连接选项传递给MongoDB\Client构造函数，而不是将它们包含在连接 URI 中。

以下示例演示如何使用MongoDB\Client构造函数的$uriOptions参数设立连接选项：

// Replace the placeholders with your actual hostname and port
$uri = 'mongodb://<hostname>:<port>/';
// Set the connection options
// Replace the placeholder with the actual path to the certificate key file
$uriOptions = [
    'tls' => true,
    'tlsCertificateKeyFile' => '/path/to/file.pem',
];
// Create a MongoDB client with the URI and options
$client = new Client($uri, $uriOptions);

注意

如果您在$uriOptions参数和连接 URI 中同时指定一个选项，则$uriOptions中的值优先。

连接 URI 选项

以下部分介绍了可以为MongoDB连接设立的选项。每个连接选项都链接到MongoDB Server手册中相应的条目。

重要

百分比编码

如果连接选项的值包含特殊字符，则必须先对该值进行百分号编码，然后才能将其包含在连接 URI 中。您可以使用 rawurlencode() 方法根据 RFC 3986 中指定的 URI 语法对这些值进行编码。

将连接选项包含在$uriOptions参数中时，不对连接选项进行百分号编码。

要了解详情，请参阅以下资源：

副本集选项

连接选项	说明
directConnection	数据类型：`bool` MongoDB\客户端示例：`$uriOptions = ['directConnection' => true];` 连接 URI 示例：`directConnection=true`
replicaSet	数据类型：`string` MongoDB\客户端示例：`$uriOptions = ['replicaSet' => 'replicaSetName'];` 连接 URI 示例：`replicaSet=replicaSetName`

连接选项

TLS 选项

要学习；了解PHP库中提供的 TLS 选项，请参阅TLS页面。

超时选项

连接选项	说明
connectTimeoutMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['connectTimeoutMS' => 2000];` 连接 URI 示例：`connectTimeoutMS=2000`
socketTimeoutMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['socketTimeoutMS' => 20000];` 连接 URI 示例：`socketTimeoutMS=20000`

压缩选项

连接选项	说明
compressors	数据类型：`string` MongoDB\客户端示例：`$uriOptions = ['compressors' => 'snappy,zstd,zlib'];` 连接 URI 示例：`compressors=snappy,zstd,zlib`
zlibCompressionLevel	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['zlibCompressionLevel' => 3];` 连接 URI 示例：`zlibCompressionLevel=3`

写关注选项

连接选项	说明
w	数据类型：`string` MongoDB\客户端示例：`$uriOptions = ['w' => 'majority'];` 连接 URI 示例：`w=majority`
wtimeoutMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['wTimeoutMS' => 10000];` 连接 URI 示例：`wTimeoutMS=10000`
journal	数据类型：`bool` MongoDB\客户端示例：`$uriOptions = ['journal' => true];` 连接 URI 示例：`journal=true`

读关注选项

连接选项	说明
readConcernLevel	数据类型：`string` MongoDB\客户端示例：`$uriOptions = ['readConcernLevel' => 'majority'];` 连接 URI 示例：`readConcernLevel=majority`

读取偏好选项

连接选项

说明

readPreference

数据类型：MongoDB\驱动程序\ReadPreference
MongoDB\客户端示例：$uriOptions = ['readPreference' => 'secondaryPreferred'];
连接 URI 示例：readPreference=secondaryPreferred

maxStalenessSeconds

数据类型：int
MongoDB\客户端示例：$uriOptions = ['maxStalenessSeconds' => 30];
连接 URI 示例：maxStalenessSeconds=30

readPreferenceTags

数据类型：array
MongoDB\客户端示例：

$uriOptions = [
    'readPreferenceTags' => [
        ['dc' => 'ny', 'rack' => 'r1'],
        [],
    ],
];

连接 URI 示例：readPreferenceTags=dc:ny,rack:r1&readPreferenceTags=

身份验证选项

要学习；了解PHP库中提供的身份验证选项，请参阅身份验证机制。

服务器选择和发现选项

连接选项	说明
localThresholdMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['localThresholdMS' => 20];` 连接 URI 示例：`localThresholdMS=20`
serverSelectionTimeoutMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['serverSelectionTimeoutMS' => 5000];` 连接 URI 示例：`serverSelectionTimeoutMS=5000`
serverSelectionTryOnce	数据类型：`bool` MongoDB\客户端示例：`$uriOptions = ['serverSelectionTryOnce' => false];` 连接 URI 示例：`serverSelectionTryOnce=false`
heartbeatFrequencyMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['heartbeatFrequencyMS' => 30000];` 连接 URI 示例：`heartbeatFrequencyMS=30000`
socketCheckIntervalMS	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['socketCheckIntervalMS' => 4000];` 连接 URI 示例：`socketCheckIntervalMS=4000`

其他配置

连接选项	说明
appName	数据类型：`string` MongoDB\客户端示例：`$uriOptions = ['appName' => 'myApp'];` 连接 URI 示例：`appName=myApp`
retryReads	数据类型：`bool` MongoDB\客户端示例：`$uriOptions = ['retryReads' => false];` 连接 URI 示例：`retryReads=false`
retryWrites	数据类型：`bool` MongoDB\客户端示例：`$uriOptions = ['retryWrites' => false];` 连接 URI 示例：`retryWrites=false`
loadBalanced	数据类型：`bool` MongoDB\客户端示例：`$uriOptions = ['loadBalanced' => true];` 连接 URI 示例：`loadBalanced=true`
SrvMaxHosts	数据类型：`int` MongoDB\客户端示例：`$uriOptions = ['srvMaxHosts' => 5];` 连接 URI 示例：`srvMaxHosts=5`

注意

智能工作负载管理 (IWM) 中的负载削减

如果带有 SystemOverloadedError 或 RetryableError 标签的错误导致您的应用程序出现故障或出现在您的应用程序日志中，则说明您的集群上可能已启用负载削减 (Load Shedding)，并且您的驱动程序可能未升级到支持该功能的版本。我们建议将您的 MongoDB PHP 库升级到 2.3 或更高版本。如果您在升级后仍然看到这些错误，可以通过服务器端更改（例如查看您的负载削减配置）或通过应用程序端更改（例如实现自定义错误处理或客户端请求限制）来解决这些错误。根据您的情况，应用程序端更改可能是更可取或必要的。

负载削减 (Load Shedding) 是 IWM 的一项功能，有助于在持续过载期间通过拒绝多余的操作来管理服务器负载。此功能适用于 MongoDB 9.0 及更高版本。

For more information about IWM or handling overload errors, see the Intelligent Workload Management page or Overload Errors page in the Atlas documentation.

API 文档

有关MongoDB\Client类的更多信息，请参阅以下PHP库API文档：

MongoDB\Client

有关MongoDB\Driver\ReadPreference类的更多信息，请参阅以下PHP扩展API文档：

MongoDB\Driver\ReadPreference