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	bool	如果為 true，則驅動程式會在透過 SASL 驗證之前解析伺服器 IP 位址的實際主機名稱。某些底層 GSSAPI 層已經這樣做，但此功能可能會在其組態中停用 (例如 krb.conf)。預設為 false。 此選項是 "authMechanismProperties" URI 選項的 "CANONICALIZE_HOST_NAME" 屬性的已淘汰別名。
compressors	字串	用戶端想要使用的優先順序、逗號分隔的壓縮器清單。僅當用戶端和伺服器共用任何通用壓縮器時，才會壓縮訊息，並且每個方向使用的壓縮器將取決於伺服器或驅動程式的個別組態。有關詳細資訊，請參閱 » 驅動程式壓縮規範。
connectTimeoutMS	int	嘗試連線的逾時時間（以毫秒為單位）。預設值為 10,000 毫秒。
directConnection	bool	當連線字串中僅提供單一主機時，可以使用此選項來控制複本集探索行為。預設情況下，在連線字串中提供單一成員將建立直接連線或探索其他成員，具體取決於是否省略或存在 "replicaSet" URI 選項。指定 false 以強制執行探索 (如果省略了 "replicaSet")，或指定 true 以強制建立直接連線 (如果存在 "replicaSet")。
gssapiServiceName	字串	連線到 Kerberos 化 MongoDB 實例時，設定 Kerberos 服務名稱。此值必須符合 MongoDB 實例上設定的服務名稱 (即 » saslServiceName 伺服器參數)。預設值為 "mongodb"。 此選項是 "authMechanismProperties" URI 選項的 "SERVICE_NAME" 屬性的已淘汰別名。
heartbeatFrequencyMS	int	指定驅動程式檢查 MongoDB 拓撲之間的時間間隔（以毫秒為單位），從上一次檢查結束到下一次檢查開始計算。預設值為 60,000 毫秒。 根據 » 伺服器探索和監控規範，此值不能小於 500 毫秒。
journal	bool	對應於預設寫入關注的 journal 參數。如果為 true，則寫入將需要 MongoDB 確認該操作已寫入日誌。有關詳細資訊，請參閱 MongoDB\Driver\WriteConcern。
loadBalanced	bool	指定驅動程式是否透過負載平衡器連線到 MongoDB 叢集。如果為 true，則驅動程式可能只連線到單一主機（由連線字串或 SRV 查詢指定），"directConnection" URI 選項不能為 true，並且必須省略 "replicaSet" URI 選項。預設值為 false。
localThresholdMS	int	在解析讀取偏好設定時，從多個適合的 MongoDB 實例中選擇的延遲視窗大小（以毫秒為單位）。預設值為 15 毫秒。
maxStalenessSeconds	int	對應於讀取偏好的 "maxStalenessSeconds"。以秒為單位指定一個次要節點在客戶端停止將其用於讀取操作之前可以過時多久。預設情況下，沒有最大陳舊時間，客戶端在選擇將讀取操作導向何處時不會考慮次要節點的延遲。詳情請參閱 MongoDB\Driver\ReadPreference。 如果指定了，最大陳舊時間必須是一個大於或等於 MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS（即 90 秒）的有符號 32 位整數。
密碼	字串	用於身份驗證的用戶密碼。如果密碼包含特殊字元，則此選項很有用，否則這些字元需要針對連線 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	bool	指定驅動程式是否應自動重試因暫時性網路錯誤或副本集選舉而失敗的某些讀取操作。此功能需要 MongoDB 3.6+。預設值為 true。 有關詳細資訊，請參閱 » 可重試讀取規格。
retryWrites	bool	指定驅動程式是否應自動重試因暫時性網路錯誤或副本集選舉而失敗的某些寫入操作。此功能需要 MongoDB 3.6+。預設值為 true。 有關詳細資訊，請參閱 MongoDB 手冊中的 » 可重試寫入。
safe	bool	如果為 true，則為預設寫入關注的 w 參數指定 1。如果為 false，則指定 0。詳情請參閱 MongoDB\Driver\WriteConcern。 此選項已過時，不應使用。
serverSelectionTimeoutMS	int	指定在拋出例外之前，阻止伺服器選擇的毫秒數。預設值為 30,000 毫秒。
serverSelectionTryOnce	bool	當為 true 時，指示驅動程式在伺服器選擇失敗後精確掃描 MongoDB 部署一次，然後選擇一個伺服器或引發錯誤。當為 false 時，驅動程式會阻止並搜尋伺服器直到 "serverSelectionTimeoutMS" 值。預設值為 true。
socketCheckIntervalMS	int	如果最近未使用某個 Socket，驅動程式必須在使用它進行任何操作之前，透過 hello 命令檢查它。預設值為 5,000 毫秒。
socketTimeoutMS	int	在 Socket 上嘗試發送或接收的時間（以毫秒為單位），然後超時。預設值為 300,000 毫秒（即五分鐘）。
srvMaxHosts	int	在初始填充種子列表時，或在 SRV 輪詢期間，將新主機新增到拓撲時，隨機選取 SRV 結果的最大數量。預設值為 0（即沒有最大值）。
srvServiceName	字串	在初始 DNS 種子列表探索和 SRV 輪詢中用於 SRV 查閱的服務名稱。預設值為 "mongodb"。
ssl	bool	如果為 true，則使用 TLS/SSL 啟動連線。預設值為 false。 此選項是 "tls" URI 選項的已過時別名。
tls	bool	如果為 true，則使用 TLS/SSL 啟動連線。預設值為 false。
tlsAllowInvalidCertificates	bool	指定當伺服器的 TLS 憑證無效時，驅動程式是否應產生錯誤。預設值為 false。 警告 停用憑證驗證會產生漏洞。
tlsAllowInvalidHostnames	bool	指定當伺服器的主機名稱與 TLS 憑證指定的主機名稱不符時，驅動程式是否應產生錯誤。預設值為 false。 警告 停用憑證驗證會產生漏洞。允許無效的主機名稱可能會使驅動程式暴露於 » 中間人攻擊。
tlsCAFile	字串	檔案的路徑，其中包含在建立 TLS 連線時要視為受信任的單個或一組憑證授權單位。預設會使用系統憑證存放區。
tlsCertificateKeyFile	字串	用戶端憑證檔案或用戶端私鑰檔案的路徑；如果兩者都需要，則應將檔案串連在一起。
tlsCertificateKeyFilePassword	字串	用於解密用戶端私鑰（即 "tlsCertificateKeyFile" URI 選項）以用於 TLS 連線的密碼。
tlsDisableCertificateRevocationCheck	bool	如果為 true，則驅動程式不會嘗試檢查憑證撤銷狀態（例如 OCSP、CRL）。預設值為 false。
tlsDisableOCSPEndpointCheck	bool	如果為 true，則如果需要（即沒有訂閱 OCSP 回應），驅動程式不會嘗試聯絡 OCSP 回應器端點。預設值為 false。
tlsInsecure	bool	盡可能放寬 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	int	指定用於 zlib 壓縮器的壓縮層級。如果 zlib 未包含在 "compressors" URI 選項中，則此選項無效。有關詳細資訊，請參閱 » 驅動程式壓縮規格。

driverOptions

driverOptions

選項	型別	說明
allow_invalid_hostname	bool	如果為 true，則停用主機名稱驗證。預設值為 false。 允許無效的主機名稱可能會使驅動程式暴露於 » 中間人攻擊。 此選項是 "tlsAllowInvalidHostnames" URI 選項的已過時別名。
autoEncryption	陣列	提供選項來啟用自動用戶端欄位層級加密。 注意: 自動加密是一項僅限企業的功能，僅適用於集合的操作。不支援對資料庫或檢視的操作使用自動加密，未繞過的操作將導致錯誤（請參閱 » libmongocrypt：自動加密允許清單）。若要繞過所有操作的自動加密，請將 bypassAutoEncryption 設定為 true。 自動加密要求已驗證的使用者具有 » listCollections 權限動作。 明確加密/解密和自動解密是一項社群功能。當 bypassAutoEncryption 為 true 時，驅動程式仍然可以自動解密。 支援下列選項 自動加密選項 選項 型別 說明 keyVaultClient MongoDB\Driver\Manager 用於將資料金鑰查詢路由到單獨 MongoDB 叢集的 Manager。預設情況下，會使用目前的 Manager 和叢集。 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 array|object 集合命名空間與本機 JSON 結構描述的對應。這用於設定自動加密。有關詳細資訊，請參閱 MongoDB 手冊中的 » 自動加密規則。在 schemaMap 和 encryptedFieldsMap 中指定集合都是錯誤的。 注意: 提供 schemaMap 比依賴從伺服器取得的 JSON 結構描述更安全。它可防止惡意的伺服器通告虛假的 JSON 結構描述，這可能會欺騙用戶端傳送應加密的未加密資料。 注意: 在 schemaMap 中提供的結構描述僅適用於設定用戶端加密的自動加密。JSON 結構描述中的其他驗證規則不會由驅動程式強制執行，並將導致錯誤。 bypassAutoEncryption bool 如果為 true，則不會自動產生 mongocryptd。這用於停用自動加密。預設值為 false。 bypassQueryAnalysis bool 若為 true，則會停用對傳出指令的自動分析，並且不會自動產生 mongocryptd。這讓針對索引欄位進行明確加密的使用案例得以實現，而無需企業授權的 crypt_shared 函式庫或 mongocryptd 程序。預設值為 false。 encryptedFieldsMap array|object 集合命名空間對應到 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	若未指定驅動程式選項或其對應的 URI 選項 (如果有的話)，則會使用 SSL 環境選項 作為回退。請注意，此擴充功能不會查詢預設的串流環境 (即 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	bool	若為 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	bool	如果為 true，則停用憑證驗證。預設值為 false。 此選項是 "tlsAllowInvalidCertificates" URI 選項的已過時別名。