/ /

/ /

指定连接选项

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\Client 示例：`$uriOptions = ['directConnection' => true];` 连接 URI 示例：`directConnection=true`
replicaSet	数据类型：`string` MongoDB\Client 示例：`$uriOptions = ['replicaSet' => 'replicaSetName'];` 连接 URI 示例：`replicaSet=replicaSetName`

连接选项

TLS 选项

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

超时选项

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

压缩选项

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

写关注选项

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

读关注选项

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

读取偏好选项

连接选项

说明

readPreference

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

maxStalenessSeconds

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

readPreferenceTags

数据类型：array
MongoDB\Client 示例：

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

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

身份验证选项

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

服务器选择和发现选项

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

其他配置

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

API 文档

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

MongoDB\Client

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

MongoDB\Driver\ReadPreference

后退

选择连接目标

来年

Stable API