Php/docs/mongodb-driver-manager.construct

来自菜鸟教程
跳转至：导航、​搜索


MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Create new MongoDB Manager


说明

final public MongoDB\Driver\Manager::__construct ([ string $uri = "mongodb://127.0.0.1/" [, array $uriOptions = array() [, array $driverOptions = array() ]]] )

Constructs a new MongoDB\Driver\Manager object with the specified options.

Note:

Per the » Server Discovery and Monitoring Specification, this constructor performs no I/O. Connections will be initialized on demand, when the first operation is executed.

Note:

When specifying any SSL or TLS URI options via the connection string or uriOptions parameter, the driver will implicitly enable TLS for its connections. To avoid this, either explicitly disable the tls option or don't specify any TLS options.

Note:

On Unix platforms, the MongoDB driver is sensitive to scripts that use the fork() system call without also calling exec(). Users are advised not to re-use MongoDB\Driver\Manager instances in a forked child process.

参数

uri

A » mongodb:// connection URI:

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

For details on supported URI options, see » Connection String Options in the MongoDB manual. » Connection pool options are not supported, as the PHP driver does not implement connection pools.

The uri is a URL, hence any special characters in its components need to be URL encoded according to » RFC 3986. This is particularly relevant to the username and password, which can often include special characters such as @, :, or %. When connecting via a Unix domain socket, the socket path may contain special characters such as slashes and must be encoded. The rawurlencode() function may be used to encode constituent parts of the URI.

The defaultAuthDb component may be used to specify the database name associated with the user's credentials; however the authSource URI option will take priority if specified. If neither defaultAuthDb nor authSource are specified, the admin database will be used by default. The defaultAuthDb component has no effect in the absence of user credentials.

uriOptions

Additional » connection string options, which will overwrite any options with the same name in the uri parameter.

uriOptions
Option Type Description
appname string

MongoDB 3.4+ has the ability to annotate connections with metadata provided by the connecting client. This metadata is included in the server's logs upon establishing a connection and also recorded in slow query logs when database profiling is enabled.

This option may be used to specify an application name, which will be included in the metadata. The value cannot exceed 128 characters in length.

authMechanism string

The authentication mechanism that MongoDB will use to authenticate

the connection. For additional details and a list of supported values, see » Authentication Options

in the MongoDB manual.

authMechanismProperties array

Properties for the selected authentication mechanism. For additional details and a list of supported properties, see the » Driver Authentication Specification.

Note:

When not specified in the URI string, this option is expressed as an array of key/value pairs. The keys and values in this array should be strings.

authSource string

The database name associated with the user's credentials. Defaults to the database component of the connection URI, or the admin database if both are unspecified.

For authentication mechanisms that delegate credential storage to other services (e.g. GSSAPI), this should be "$external".

canonicalizeHostname bool

If true, the driver will resolve the real hostname for the server IP address before authenticating via SASL. Some underlying GSSAPI layers already do this, but the functionality may be disabled in their config (e.g. krb.conf). Defaults to false.

This option is a deprecated alias for the "CANONICALIZE_HOST_NAME" property of the "authMechanismProperties" URI option.

compressors string

A prioritized, comma-delimited list of compressors that the client

wants to use. Messages are only compressed if the client and server share any compressors in common, and the compressor used in each direction will depend on the individual configuration of the server or driver. See the » Driver Compression Specification

for more information.

connectTimeoutMS int

The time in milliseconds to attempt a connection before timing out. Defaults to 10,000 milliseconds.

directConnection bool

This option can be used to control replica set discovery behavior

when only a single host is provided in the connection string. By default, providing a single member in the connection string will establish a direct connection or discover additional members depending on whether the "replicaSet" URI option is omitted or present, respectively. Specify false to force discovery to occur (if "replicaSet" is omitted) or specify true to force a direct connection (if

"replicaSet" is present).

gssapiServiceName string

Set the Kerberos service name when connecting to Kerberized MongoDB instances. This value must match the service name set on MongoDB instances (i.e. » saslServiceName server parameter). Defaults to "mongodb".

This option is a deprecated alias for the "SERVICE_NAME" property of the "authMechanismProperties" URI option.

heartbeatFrequencyMS int

Specifies the interval in milliseconds between the driver's checks of the MongoDB topology, counted from the end of the previous check until the beginning of the next one. Defaults to 60,000 milliseconds.

Per the » Server Discovery and Monitoring Specification, this value cannot be less than 500 milliseconds.

journal bool

Corresponds to the default write concern's

journal parameter. If true, writes will require acknowledgement from MongoDB that the operation has been written to the journal. For details, see

MongoDB\Driver\WriteConcern.

localThresholdMS int

The size in milliseconds of the latency window for selecting among

multiple suitable MongoDB instances while resolving a read

preference. Defaults to 15 milliseconds.

maxStalenessSeconds int

Corresponds to the read preference's "maxStalenessSeconds". Specifies, in seconds, how stale a secondary can be before the client stops using it for read operations. By default, there is no maximum staleness and clients will not consider a secondary’s lag when choosing where to direct a read operation. For details, see MongoDB\Driver\ReadPreference.

If specified, the max staleness must be a signed 32-bit integer greater than or equal to MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS (i.e. 90 seconds).

password string The password for the user being authenticated. This option is useful

if the password contains special characters, which would otherwise need to be URL encoded for the connection URI.

readConcernLevel string Corresponds to the read concern's level

parameter. Specifies the level of read isolation. For details, see MongoDB\Driver\ReadConcern.

readPreference string

Corresponds to the read preference's mode

parameter. Defaults to "primary". For details,

see MongoDB\Driver\ReadPreference.

readPreferenceTags array

Corresponds to the read preference's tagSets parameter. Tag sets allow you to target read operations to specific members of a replica set. For details, see MongoDB\Driver\ReadPreference.

Note:

When not specified in the URI string, this option is expressed as an array consistent with the format expected by MongoDB\Driver\ReadPreference::__construct().

replicaSet string

Specifies the name of the replica set.

retryReads bool

Specifies whether or not the driver should automatically retry certain read operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to true.

See the » Retryable Reads Specification for more information.

retryWrites bool

Specifies whether or not the driver should automatically retry certain write operations that fail due to transient network errors or replica set elections. This functionality requires MongoDB 3.6+. Defaults to true.

See » Retryable Writes in the MongoDB manual for more information.

safe bool

If true, specifies 1 for the default write concern's w parameter. If false, 0 is specified. For details, see MongoDB\Driver\WriteConcern.

This option is deprecated and should not be used.

serverSelectionTimeoutMS int

Specifies how long in milliseconds to block for server selection before throwing an exception. Defaults to 30,000 milliseconds.

serverSelectionTryOnce bool

When true, instructs the driver to scan the MongoDB deployment

exactly once after server selection fails and then either select a server or raise an error. When false, the driver blocks and searches for a server up to the "serverSelectionTimeoutMS" value. Defaults to

true.

slaveOk bool

Specifies "secondaryPreferred" for the read preference mode if true. For details, see MongoDB\Driver\ReadPreference.

This option is deprecated and should not be used.

socketCheckIntervalMS int

If a socket has not been used recently, the driver must check it via

an isMaster command before using it for any

operation. Defaults to 5,000 milliseconds.

socketTimeoutMS int

The time in milliseconds to attempt a send or receive on a socket

before timing out. Defaults to 300,000 milliseconds (i.e. five

minutes).

ssl bool

Initiates the connection with TLS/SSL if true. Defaults to false.

This option is a deprecated alias for the "tls" URI option.

tls bool

Initiates the connection with TLS/SSL if true. Defaults to false.

tlsAllowInvalidCertificates bool

Specifies whether or not the driver should error when the server's TLS certificate is invalid. Defaults to false.

Warning

Disabling certificate validation creates a vulnerability.

tlsAllowInvalidHostnames bool

Specifies whether or not the driver should error when there is a mismatch between the server's hostname and the hostname specified by the TLS certificate. Defaults to false.

Warning

Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

tlsCAFile string

Path to file with either a single or bundle of certificate

authorities to be considered trusted when making a TLS connection.

The system certificate store will be used by default.

tlsCertificateKeyFile string

Path to the client certificate file or the client private key file;

in the case that they both are needed, the files should be

concatenated.

tlsCertificateKeyFilePassword string

Password to decrypt the client private key (i.e.

"tlsCertificateKeyFile" URI option) to be used

for TLS connections.

tlsDisableCertificateRevocationCheck bool

If true, the driver will not attempt to check certificate revocation status (e.g. OCSP, CRL). Defaults to false.

tlsDisableOCSPEndpointCheck bool

If true, the driver will not attempt to contact an OCSP responder

endpoint if needed (i.e. an OCSP response is not stapled). Defaults

to false.

tlsInsecure bool

Relax TLS constraints as much as possible. Specifying true for this option has the same effect as specifying true for both the "tlsAllowInvalidCertificates" and "tlsAllowInvalidHostnames" URI options. Defaults to false.

Warning

Disabling certificate validation creates a vulnerability. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

username string The username for the user being authenticated. This option is useful

if the username contains special characters, which would otherwise need to be URL encoded for the connection URI.

w string

Corresponds to the default write concern's w

parameter. For details, see

MongoDB\Driver\WriteConcern.

wTimeoutMS string

Corresponds to the default write concern's wtimeout parameter. Specifies a time limit, in milliseconds, for the write concern. For details, see MongoDB\Driver\WriteConcern.

If specified, wTimeoutMS must be a signed 32-bit integer greater than or equal to zero.

zlibCompressionLevel int

Specifies the compression level to use for the zlib compressor. This

option has no effect if zlib is not included in the "compressors" URI option. See the » Driver Compression Specification

for more information.

driverOptions
{| |+ driverOptions !width="33%"| Option !width="33%"| Type !width="33%"| Description |- | allow_invalid_hostname | bool |

Disables hostname validation if true. Defaults to false.

Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.

This option is a deprecated alias for the "tlsAllowInvalidHostnames" URI option.

|- | autoEncryption | array |

Provides options to enable automatic client-side field level encryption. The following options are supported:

Options for automatic encryption
Option Type Description
keyVaultClient MongoDB\Driver\Manager The Manager used to route data key queries to a separate MongoDB cluster. By default, the current Manager and cluster is used.
keyVaultNamespace string A fully qualified namespace (e.g. "databaseName.collectionName") denoting the collection that contains all data keys used for encryption and decryption.
kmsProviders array

A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Currently aws or localare supported and at least one must be specified.

The format for aws is as follows:

aws: {
    accessKeyId: <string>,
    secretAccessKey: <string>
}

The format for local is as follows:

local: {
    // The master key used to encrypt/decrypt data keys
    key: <96-byte MongoDB\BSON\Binary with subtype 0>
}
schemaMap array

Allows specifying a local JSON schema that is used to configure encryption.

Note:

Supplying a schemaMap provides more security than relying on JSON schemas obtained from the server. It protects against a malicious server advertising a false JSON schema, which could trick the client into sending unencrypted data that should be encrypted.

Note:

Schemas supplied in the schemaMap only apply to configuring automatic encryption for client side encryption. Other validation rules in the JSON schema will not be enforced by the driver and will result in an error.

bypassAutoEncryption bool With this option set to true, mongocryptd

will not be spawned automatically. This is used to disable automatic encryption.

extraOptions array The extraOptions relate to the

mongocryptd process. See the » Client-Side Encryption Specification for more information.

Note:

Automatic encryption is an enterprise only feature that only applies to operations on a collection. Automatic encryption is not supported for operations on a database or view, and operations that are not bypassed will result in error. To bypass automatic encryption for all operations, set bypassAutoEncryption=true in autoEncryption. For more information on whitelisted operations, see the » Client-Side Encryption Specification.

|- | ca_dir | string

|

Path to a correctly hashed certificate directory. The system certificate store will be used by default.

|- | ca_file | string |

Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection. The system certificate store will be used by default.

This option is a deprecated alias for the "tlsCAFile" URI option.

|- | context | resource |

SSL context options to be used as fallbacks if a driver option or its equivalent URI option, if any, is not specified. Note that the driver does not consult the default stream context (i.e. stream_context_get_default()). The following context options are supported:

SSL context option fallbacks
Driver option Context option (fallback)
ca_dir capath
ca_file cafile
pem_file local_cert
pem_pwd passphrase
weak_cert_validation allow_self_signed

This option is supported for backwards compatibility, but should be considered deprecated.

|- | crl_file | string | Path to a certificate revocation list file. |- | driver | array |

Allows custom drivers to append their own metadata to the server handshake. By default, the driver submits its own name, version, and platform (i.e. PHP version) in the handshake. Custom drivers can specify strings for the "name", "version", and "platform" keys of this array, which will be appended to the respective field(s) in the handshake document.

Note:

Handshake information is limited to 512 bytes. The driver will truncate handshake data to fit within this 512-byte string. Drivers and ODMs are encouraged to keep their own metadata concise.

|- | pem_file | string |

Path to a PEM encoded certificate to use for client authentication.

This option is a deprecated alias for the "tlsCertificateKeyFile" URI option.

|- | pem_pwd | string |

Passphrase for the PEM encoded certificate (if applicable).

This option is a deprecated alias for the "tlsCertificateKeyFilePassword" URI option.

|- | weak_cert_validation | bool |

Disables certificate validation if true. Defaults to false

This option is a deprecated alias for the "tlsAllowInvalidHostnames" URI option.

|}


错误／异常


更新日志

版本 说明
PECL mongodb 1.8.0

Added the "directConnection", "tlsDisableCertificateRevocationCheck", and "tlsDisableOCSPEndpointCheck" URI options.

Added the "driver" driver option.

PECL mongodb 1.7.0

Added the "autoEncryption" driver option.

Specifying any SSL or TLS option via the driverOptions parameter will now implicitly enable TLS, as is done for the corresponding URI options.

PECL mongodb 1.6.0

Added the "retryReads", "tls", "tlsAllowInvalidCertificates", "tlsAllowInvalidHostnames", "tlsCAFile", "tlsCertificateKeyFile", "tlsCertificateKeyFilePassword", and "tlsInsecure" URI options.

The "retryWrites" URI option defaults to true.

Specifying any SSL or TLS URI option via the connection string or uriOptions parameter will now implicitly enable TLS unless ssl or tls is false. TLS is not implicitly enabled for any options in the driverOptions parameter, which is unchanged from previous versions.

PECL mongodb 1.5.0 "wtimeoutMS" is now always validated and applied to

the write concern. Previously, the option was ignored if "w" was <= 1, since the timeout only applies to replication.

PECL mongodb 1.4.0 Added the "compressors",

"retryWrites", and "zlibCompressionLevel" URI options.

PECL mongodb 1.3.0 The uriOptions argument now accepts

"authMechanism" and "authMechanismProperties" options. Previously, these options were only supported in the uri argument.

PECL mongodb 1.2.0

The uri argument defaults to "mongodb://127.0.0.1/". The default port remains 27017.

Added the "appname" URI option.

Added the "allow_invalid_hostname", "ca_file", "ca_dir", "clr_file", "pem_file", "pem_pwd", and "weak_cert_validation" driver options.

The PHP Streams API is no longer used for socket communication. The "connectTimeoutMS" URI option now defaults to 10 seconds instead of default_socket_timeout in previous versions. Additionally, the driver no longer supports all SSL context options via the "context" driver option.

PECL mongodb 1.1.0 The uri argument is optional and defaults to

"mongodb://localhost:27017/".


范例

Example #1 MongoDB\Driver\Manager::__construct() basic examples

Connecting to standalone MongoDB node:


<?php$manager = new MongoDB\Driver\Manager("mongodb://example.com:27017");?>

Connecting to standalone MongoDB node via a Unix domain socket. The socket path may include special characters such as slashes and should be encoded with rawurlencode().


<?php$manager = new MongoDB\Driver\Manager("mongodb://" . rawurlencode("/tmp/mongodb-27017.sock"));?>

Connecting to a replica set:


<?php$manager = new MongoDB\Driver\Manager("mongodb://rs1.example.com,rs2.example.com/?replicaSet=myReplicaSet");?>

Connecting to a sharded cluster (i.e. one or more mongos instances):


<?php$manager = new MongoDB\Driver\Manager("mongodb://mongos1.example.com,mongos2.example.com/");?>

Connecting to MongoDB with authentication credentials for a particular user and database:


<?php$manager = new MongoDB\Driver\Manager("mongodb://myusername:mypassword@example.com/?authSource=databaseName");?>

Connecting to MongoDB with authentication credentials for a particular user and database, where the username or password includes special characters (e.g. @, :, %). In the following example, the password string myp@ss:w%rd has been manually escaped; however, rawurlencode() may also be used to escape URI components that may contain special characters.


<?php$manager = new MongoDB\Driver\Manager("mongodb://myusername:myp%40ss%3Aw%25rd@example.com/?authSource=databaseName");?>

Connecting to MongoDB with X509 authentication:


<?php$manager = new MongoDB\Driver\Manager(    "mongodb://example.com/?ssl=true&authMechanism=MONGODB-X509",    [],    [        "pem_file" => "/path/to/client.pem",    ]);?>

取自“https://cainiaojiaocheng.com/index.php?title=Php/docs/mongodb-driver-manager.construct&oldid=8998”
Powered by MediaWiki