MongoDB\Driver\Manager::__construct

参数

uri

一个 » mongodb:// 连接 URI

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[defaultAuthDb][?options]]

如果未指定，则默认为 "mongodb://127.0.0.1:27017"。

有关支持的 URI 选项的详细信息，请参阅 MongoDB 手册中的 » 连接字符串选项。 » 连接池选项 不受支持，因为扩展不实现连接池。

uri 是一个 URL，因此其组件中的任何特殊字符都需要根据 » RFC 3986 进行 URL 编码。这与用户名和密码特别相关，因为它们通常包含特殊字符，例如 @、: 或 %。通过 Unix 域套接字连接时，套接字路径可能包含斜杠等特殊字符，并且必须进行编码。 rawurlencode() 函数可用于对 URI 的组成部分进行编码。

defaultAuthDb 组件可用于指定与用户凭据关联的数据库名称；但是，如果指定了 authSource URI 选项，则它将优先。如果既未指定 defaultAuthDb 也未指定 authSource，则默认情况下将使用 admin 数据库。在没有用户凭据的情况下， defaultAuthDb 组件无效。

uriOptions

其他 » 连接字符串选项，它将覆盖 uri 参数中名称相同的任何选项。

uriOptions

选项	类型	描述
appname	字符串	MongoDB 3.4+ 能够使用连接客户端提供的元数据来注释连接。此元数据在建立连接时包含在服务器的日志中，并在启用数据库分析时记录在慢查询日志中。 此选项可用于指定应用程序名称，该名称将包含在元数据中。该值不能超过 128 个字符。
authMechanism	字符串	MongoDB 将用于对连接进行身份验证的身份验证机制。有关其他详细信息和支持值的列表，请参阅 MongoDB 手册中的 » 身份验证选项。
authMechanismProperties	数组	所选身份验证机制的属性。有关其他详细信息和支持属性的列表，请参阅 » 驱动程序身份验证规范。 注意: 未在 URI 字符串中指定时，此选项表示为键/值对的数组。此数组中的键和值应为字符串。
authSource	字符串	与用户凭据关联的数据库名称。默认为连接 URI 的数据库组件，或者如果两者均未指定，则默认为 admin 数据库。 对于将凭据存储委托给其他服务（例如 GSSAPI）的身份验证机制，这应该是 "$external"。
canonicalizeHostname	布尔值	如果为 true，则驱动程序将在通过 SASL 进行身份验证之前解析服务器 IP 地址的真实主机名。某些底层 GSSAPI 层已经执行此操作，但其功能可能在其配置（例如 krb.conf）中被禁用。默认为 false。 此选项是 "authMechanismProperties" URI 选项的 "CANONICALIZE_HOST_NAME" 属性的已弃用别名。
compressors	字符串	客户端想要使用的压缩程序的优先级逗号分隔列表。仅当客户端和服务器共享任何压缩程序时才会压缩消息，并且每个方向使用的压缩程序将取决于服务器或驱动程序的单个配置。有关更多信息，请参阅 » 驱动程序压缩规范。
connectTimeoutMS	整数	尝试连接并在超时前的时间（毫秒）。默认为 10,000 毫秒。
directConnection	布尔值	此选项可用于控制仅在连接字符串中提供单个主机时的副本集发现行为。默认情况下，在连接字符串中提供单个成员将建立直接连接或发现其他成员，具体取决于 "replicaSet" URI 选项是否被省略或存在。指定 false 以强制发现发生（如果省略了 "replicaSet"）或指定 true 以强制直接连接（如果存在 "replicaSet"）。
gssapiServiceName	字符串	连接到 Kerberized MongoDB 实例时设置 Kerberos 服务名称。此值必须与 MongoDB 实例上设置的服务名称匹配（即 » saslServiceName 服务器参数）。默认为 "mongodb"。 此选项是 "authMechanismProperties" URI 选项的 "SERVICE_NAME" 属性的已弃用别名。
heartbeatFrequencyMS	整数	指定驱动程序检查 MongoDB 拓扑的间隔（毫秒），从上一次检查结束到下一次检查开始计算。默认为 60,000 毫秒。 根据» 服务器发现和监控规范，此值不能小于 500 毫秒。
journal	布尔值	对应于默认写入关注的 journal 参数。如果为true，则写入需要 MongoDB 确认操作已写入日志。有关详细信息，请参阅MongoDB\Driver\WriteConcern。
loadBalanced	布尔值	指定驱动程序是否通过负载均衡器连接到 MongoDB 集群。如果为true，则驱动程序可能仅连接到单个主机（由连接字符串或 SRV 查找指定），"directConnection" URI 选项不能为true，并且必须省略 "replicaSet" URI 选项。默认为false。
localThresholdMS	整数	在解析读取偏好时，在多个合适的 MongoDB 实例之间进行选择时，延迟窗口的大小（以毫秒为单位）。默认为 15 毫秒。
maxStalenessSeconds	整数	对应于读取偏好的 "maxStalenessSeconds"。以秒为单位指定辅助节点在客户端停止将其用于读取操作之前可以有多陈旧。默认情况下，没有最大陈旧性，并且客户端在选择读取操作的目标位置时不会考虑辅助节点的延迟。有关详细信息，请参阅MongoDB\Driver\ReadPreference。 如果指定，则最大陈旧性必须是大于或等于MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS（即 90 秒）的有符号 32 位整数。
password	字符串	要进行身份验证的用户密码。如果密码包含特殊字符，此选项很有用，否则需要对连接 URI 进行 URL 编码。
readConcernLevel	字符串	对应于读取关注的 level 参数。指定读取隔离级别。有关详细信息，请参阅MongoDB\Driver\ReadConcern。
readPreference	字符串	对应于读取偏好的 mode 参数。默认为 "primary"。有关详细信息，请参阅MongoDB\Driver\ReadPreference。
readPreferenceTags	数组	对应于读取偏好的 tagSets 参数。标签集允许您将读取操作目标定位到副本集的特定成员。有关详细信息，请参阅MongoDB\Driver\ReadPreference。 注意：当未在 URI 字符串中指定时，此选项表示为与 MongoDB\Driver\ReadPreference::__construct() 预期的格式一致的数组。
replicaSet	字符串	指定副本集的名称。
retryReads	布尔值	指定驱动程序是否应自动重试由于瞬态网络错误或副本集选举而失败的某些读取操作。此功能需要 MongoDB 3.6+。默认为true。 有关更多信息，请参阅» 可重试读取规范。
retryWrites	布尔值	指定驱动程序是否应自动重试由于瞬态网络错误或副本集选举而失败的某些写入操作。此功能需要 MongoDB 3.6+。默认为true。 有关更多信息，请参阅 MongoDB 手册中的» 可重试写入。
safe	布尔值	如果为true，则为默认写入关注的 w 参数指定 1。如果为false，则指定 0。有关详细信息，请参阅MongoDB\Driver\WriteConcern。 此选项已弃用，不应使用。
serverSelectionTimeoutMS	整数	指定在抛出异常之前阻塞服务器选择多长时间（以毫秒为单位）。默认为 30,000 毫秒。
serverSelectionTryOnce	布尔值	当为true时，指示驱动程序在服务器选择失败后准确扫描一次 MongoDB 部署，然后选择服务器或引发错误。当为false时，驱动程序会阻塞并搜索服务器，直到 "serverSelectionTimeoutMS" 值。默认为true。
socketCheckIntervalMS	整数	如果套接字最近未使用，则驱动程序必须通过 hello 命令检查它，然后才能将其用于任何操作。默认为 5,000 毫秒。
socketTimeoutMS	整数	在超时之前尝试在套接字上发送或接收的时间（以毫秒为单位）。默认为 300,000 毫秒（即五分钟）。
srvMaxHosts	整数	在最初填充种子列表时或在 SRV 轮询期间将新主机添加到拓扑时，要随机选择的 SRV 结果的最大数量。默认为 0（即没有最大值）。
srvServiceName	字符串	在初始 DNS 种子列表发现和 SRV 轮询中用于 SRV 查找的服务名称。默认为 "mongodb"。
ssl	布尔值	如果为true，则使用 TLS/SSL 启动连接。默认为false。 此选项是 "tls" URI 选项的已弃用别名。
tls	布尔值	如果为true，则使用 TLS/SSL 启动连接。默认为false。
tlsAllowInvalidCertificates	布尔值	指定服务器的 TLS 证书无效时驱动程序是否应出错。默认为false。 警告 禁用证书验证会造成安全漏洞。
tlsAllowInvalidHostnames	布尔值	指定服务器的主机名与 TLS 证书指定的主机名不匹配时驱动程序是否应出错。默认为false。 警告 禁用证书验证会造成安全漏洞。允许无效主机名可能会使驱动程序面临» 中间人攻击的风险。
tlsCAFile	字符串	包含一个或多个证书颁发机构的文件路径，在建立 TLS 连接时，这些证书颁发机构将被视为受信任的。默认情况下将使用系统证书存储。
tlsCertificateKeyFile	字符串	客户端证书文件或客户端私钥文件的路径；如果两者都需要，则应将文件连接起来。
tlsCertificateKeyFilePassword	字符串	解密客户端私钥（即 "tlsCertificateKeyFile" URI 选项）的密码，用于 TLS 连接。
tlsDisableCertificateRevocationCheck	布尔值	如果为true，则驱动程序不会尝试检查证书吊销状态（例如 OCSP、CRL）。默认为false。
tlsDisableOCSPEndpointCheck	布尔值	如果为true，则驱动程序在需要时不会尝试联系 OCSP 响应程序端点（即 OCSP 响应未固定）。默认为false。
tlsInsecure	布尔值	尽可能放宽 TLS 约束。为此选项指定true的效果与为 "tlsAllowInvalidCertificates" 和 "tlsAllowInvalidHostnames" URI 选项都指定true相同。默认为false。 警告 禁用证书验证会造成安全漏洞。允许无效主机名可能会使驱动程序面临» 中间人攻击的风险。
username	字符串	要进行身份验证的用户用户名。如果用户名包含特殊字符，此选项很有用，否则需要对连接 URI 进行 URL 编码。
w	int|string	对应于默认写入关注的 w 参数。有关详细信息，请参阅MongoDB\Driver\WriteConcern。
wTimeoutMS	int|string	对应于默认写入关注的 wtimeout 参数。指定写入关注的时间限制（以毫秒为单位）。有关详细信息，请参阅MongoDB\Driver\WriteConcern。 如果指定，则 wTimeoutMS 必须是大于或等于零的有符号 32 位整数。
zlibCompressionLevel	整数	指定用于 zlib 压缩器的压缩级别。如果 "compressors" URI 选项中未包含 zlib，则此选项无效。有关更多信息，请参阅» 驱动程序压缩规范。

driverOptions

driverOptions

选项	类型	描述
allow_invalid_hostname	布尔值	如果为true，则禁用主机名验证。默认为false。 允许无效主机名可能会使驱动程序面临» 中间人攻击的风险。 此选项是 "tlsAllowInvalidHostnames" URI 选项的已弃用别名。
autoEncryption	数组	提供启用自动客户端侧字段级加密的选项。 注意: 自动加密是仅限企业的特性，仅适用于集合上的操作。数据库或视图上的操作不支持自动加密，并且不会绕过的操作将导致错误（请参阅» libmongocrypt：自动加密允许列表）。要绕过所有操作的自动加密，请将 bypassAutoEncryption 设置为true。 自动加密要求已认证的用户具有» listCollections权限操作。 显式加密/解密和自动解密是社区特性。当 bypassAutoEncryption 为true时，驱动程序仍然可以自动解密。 支持以下选项 自动加密选项 选项 类型 描述 keyVaultClient MongoDB\Driver\Manager 用于将数据密钥查询路由到单独的 MongoDB 集群的管理器。默认情况下，使用当前管理器和集群。 keyVaultNamespace 字符串 一个完全限定的命名空间（例如 "databaseName.collectionName"），表示包含用于加密和解密的所有数据密钥的集合。此选项是必需的。 kmsProviders 数组 一个文档，包含一个或多个 KMS 提供程序的配置，这些提供程序用于加密数据密钥。支持的提供程序包括 "aws"、"azure"、"gcp"、"kmip" 和 "local"，并且必须至少指定一个。 如果为 "aws"、"azure" 或 "gcp" 指定了一个空文档，则驱动程序将尝试使用 » 自动凭据 配置提供程序。 "aws" 的格式如下 aws: { accessKeyId: <string>, secretAccessKey: <string>, sessionToken: <optional string> } "azure" 的格式如下 azure: { tenantId: <string>, clientId: <string>, clientSecret: <string>, identityPlatformEndpoint: <optional string> // Defaults to "login.microsoftonline.com" } "gcp" 的格式如下 gcp: { email: <string>, privateKey: <base64 string>|<MongoDB\BSON\Binary>, endpoint: <optional string> // Defaults to "oauth2.googleapis.com" } "kmip" 的格式如下 kmip: { endpoint: <string> } "local" 的格式如下 local: { // 96-byte master key used to encrypt/decrypt data keys key: <base64 string>|<MongoDB\BSON\Binary> } tlsOptions 数组 一个文档，包含一个或多个 KMS 提供程序的 TLS 配置。支持的提供程序包括 "aws"、"azure"、"gcp" 和 "kmip"。所有提供程序都支持以下选项 <provider>: { tlsCaFile: <optional string>, tlsCertificateKeyFile: <optional string>, tlsCertificateKeyFilePassword: <optional string>, tlsDisableOCSPEndpointCheck: <optional bool> } schemaMap 数组|对象 集合命名空间到本地 JSON 架构的映射。这用于配置自动加密。有关更多信息，请参阅 MongoDB 手册中的 » 自动加密规则。在 schemaMap 和 encryptedFieldsMap 中同时指定一个集合是错误的。 注意： 提供 schemaMap 比依赖从服务器获取的 JSON 架构提供了更高的安全性。它可以防止恶意服务器发布虚假的 JSON 架构，这可能会欺骗客户端发送应该加密的未加密数据。 注意： 在 schemaMap 中提供的架构仅适用于配置客户端加密的自动加密。JSON 架构中的其他验证规则不会由驱动程序强制执行，并且会导致错误。 bypassAutoEncryption 布尔值 如果为 true，则不会自动生成 mongocryptd。这用于禁用自动加密。默认为 false。 bypassQueryAnalysis 布尔值 如果为 true，则将禁用对传出命令的自动分析，并且不会自动生成 mongocryptd。这使得在不需要企业许可的 crypt_shared 库或 mongocryptd 进程的情况下，显式加密查询索引字段成为可能。默认为 false。 encryptedFieldsMap 数组|对象 集合命名空间到 encryptedFields 文档的映射。这用于配置可查询加密。有关更多信息，请参阅 MongoDB 手册中的 » 字段加密和可查询性。在 encryptedFieldsMap 和 schemaMap 中同时指定一个集合是错误的。 注意： 提供 encryptedFieldsMap 比依赖从服务器获取的 encryptedFields 提供了更高的安全性。它可以防止恶意服务器发布虚假的 encryptedFields。 extraOptions 数组 extraOptions 与 mongocryptd 进程相关。支持以下选项 mongocryptdURI (字符串): 用于连接到现有 mongocryptd 进程的 URI。默认为 "mongodb://127.0.0.1:27020"。 mongocryptdBypassSpawn (布尔值): 如果为 true，则阻止驱动程序生成 mongocryptd。默认为 false。 mongocryptdSpawnPath (字符串): 搜索 mongocryptd 二进制文件的绝对路径。默认为空字符串，并参考系统路径。 mongocryptdSpawnArgs (数组): 要在生成 mongocryptd 时传递给它的字符串参数数组。默认为 ["--idleShutdownTimeoutSecs=60"]。 cryptSharedLibPath (字符串): 到 crypt_shared 共享库的绝对路径。默认为空字符串，并参考系统路径。 cryptSharedLibRequired (布尔值): 如果为 true，则要求驱动程序加载 crypt_shared。默认为 false。 有关更多信息，请参阅 » 客户端加密规范。 注意： 自动加密是仅限企业的特性，仅适用于对集合的操作。自动加密不支持对数据库或视图的操作，并且不会被绕过的操作将导致错误。要绕过所有操作的自动加密，请在 autoEncryption 中设置 bypassAutoEncryption=true。有关允许操作的更多信息，请参阅 » 客户端加密规范。
ca_dir	字符串	正确散列的证书目录的路径。默认情况下将使用系统证书存储。
ca_file	字符串	包含一个或多个证书颁发机构的文件路径，在建立 TLS 连接时，这些证书颁发机构将被视为受信任的。默认情况下将使用系统证书存储。 此选项是 "tlsCAFile" URI 选项的已弃用别名。
context	resource	SSL 上下文选项，如果未指定驱动程序选项或其等效的 URI 选项（如果有），则用作回退。请注意，扩展程序不会参考默认流上下文（即 stream_context_get_default()）。支持以下上下文选项 SSL 上下文选项回退 驱动程序选项 上下文选项（回退） ca_dir capath ca_file cafile pem_file local_cert pem_pwd passphrase weak_cert_validation allow_self_signed 此选项支持向后兼容，但应视为已弃用。
crl_file	字符串	证书吊销列表文件的路径。
disableClientPersistence	布尔值	如果为 true，则此管理器将使用新的 libmongoc 客户端，该客户端不会持久化或与其他管理器对象共享。当此管理器对象被释放时，其客户端将被销毁，并且所有连接都将关闭。默认为 false。 注意： 通常不建议禁用客户端持久性。
driver	数组	允许更高级别的库将自己的元数据附加到服务器握手。默认情况下，扩展程序在握手时提交自己的名称、版本和平台（即 PHP 版本）。可以为该数组的 "name"、"version" 和 "platform" 键指定字符串，并将附加到握手文档中相应的字段。 注意： 握手信息限制为 512 字节。扩展程序将截断握手数据以适合此 512 字节字符串。鼓励更高级别的库使其自己的元数据简洁。
pem_file	字符串	到用于客户端身份验证的 PEM 编码证书的路径。 此选项是 "tlsCertificateKeyFile" URI 选项的已弃用别名。
pem_pwd	字符串	PEM 编码证书的密码（如果适用）。 此选项是 "tlsCertificateKeyFilePassword" URI 选项的已弃用别名。
serverApi	MongoDB\Driver\ServerApi	此选项用于为管理器声明服务器 API 版本。如果省略，则不声明任何 API 版本。
weak_cert_validation	布尔值	如果为 true，则禁用证书验证。默认为 false 此选项是 "tlsAllowInvalidCertificates" URI 选项的已弃用别名。