对于 AI 代理：可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

指定连接选项

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参数中时，不对连接选项进行百分号编码。

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

副本集选项

连接选项
说明

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['directConnection' => true];
连接 URI 示例：directConnection=true

数据类型：string
MongoDB\客户端 示例：$uriOptions = ['replicaSet' => 'replicaSetName'];
连接 URI 示例：replicaSet=replicaSetName

连接选项

TLS 选项

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

超时选项

连接选项
说明

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

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

压缩选项

连接选项
说明

数据类型：string
MongoDB\客户端 示例：$uriOptions = ['compressors' => 'snappy,zstd,zlib'];
连接 URI 示例：compressors=snappy,zstd,zlib

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

写关注选项

连接选项
说明

数据类型：string
MongoDB\客户端 示例：$uriOptions = ['w' => 'majority'];
连接 URI 示例：w=majority

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

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['journal' => true];
连接 URI 示例：journal=true

读关注选项

连接选项
说明

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

读取偏好选项

连接选项
说明

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

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

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

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

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

身份验证选项

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

服务器选择和发现选项

连接选项
说明

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

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

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['serverSelectionTryOnce' => false];
连接 URI 示例：serverSelectionTryOnce=false

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

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

enableOverloadRetargeting

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['enableOverloadRetargeting' => true];
连接 URI 示例：enableOverloadRetargeting=true
注：此选项仅在 MongoDB 9.0 或更高版本上支持。

maxAdaptiveRetries

数据类型：int
MongoDB\客户端 示例：$uriOptions = ['maxAdaptiveRetries' => 3];
连接 URI 示例：maxAdaptiveRetries=3
注：此选项仅在 MongoDB 9.0 或更高版本上支持。

其他配置

连接选项
说明

数据类型：string
MongoDB\客户端 示例：$uriOptions = ['appName' => 'myApp'];
连接 URI 示例：appName=myApp

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['retryReads' => false];
连接 URI 示例：retryReads=false

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['retryWrites' => false];
连接 URI 示例：retryWrites=false

数据类型：bool
MongoDB\客户端 示例：$uriOptions = ['loadBalanced' => true];
连接 URI 示例：loadBalanced=true

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

注意

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

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

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

有关 IWM 或处理超载错误的更多信息，请参阅 智能工作负载管理 页面或 超载错误 页面中的 Atlas 文档。

API 文档

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

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

后退
选择连接目标
来年
Stable API
给本页内容打分

在此页面上