Create new MongoDB Manager

# 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.

> 注意: 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.

> 注意: Unix プラットフォームの MongoDB ドライバーは、 exec() システムコールを呼ばすに fork() システムコールを使っているスクリプトの影響を受けます。 MongoDB\Driver\Manager のインスタンスを、 フォークした子プロセスで再利用しないことをおすすめします。

### パラメータ

`uri`

  A » mongodb:// connection URI:

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

  For details on supported 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.

`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. 注意: 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. For authentication mechanisms that delegate credential storage to other services (e.g. GSSAPI), this should be "$external".
  canonicalizeHostname | boolean | 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 | integer | The time in milliseconds to attempt a connection before timing out. Defaults to 10,000 milliseconds.
  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 | integer | 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 | boolean | 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 | integer | 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 | integer | 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 preferences's `mode` parameter. Defaults to "primary". For details, see MongoDB\Driver\ReadPreference.
  readPreferenceTags | array | Corresponds to the read preferences's `tagSets` parameter. Tag sets allow you to target read operations to specific members of a replica set. For details, see MongoDB\Driver\ReadPreference. 注意: 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.
  retryWrites | boolean | If `TRUE`, the driver will automatically retry certain write operations that fail due to transient network errors or replica set elections. Defaults to `FALSE`. See » Retryable Writes in the MongoDB manual for more information.
  safe | boolean | 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 | integer | Specifies how long in milliseconds to block for server selection before throwing an exception. Defaults to 30,000 milliseconds.
  serverSelectionTryOnce | boolean | 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 | boolean | 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 | integer | 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 | integer | 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 | boolean | Initiates the connection with TLS/SSL if `TRUE`. Defaults to `FALSE`.
  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 | integer|string | Corresponds to the default write concern's `w` parameter. For details, see MongoDB\Driver\WriteConcern.
  wTimeoutMS | integer|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 | integer | 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
  Option | Type | Description
  --- | --- | ---
  allow_invalid_hostname | boolean | Disables hostname validation if `TRUE`. Defaults to `FALSE`. Allowing invalid hostnames may expose the driver to a » man-in-the-middle attack.
  ca_dir | string | Path to a correctly hashed certificate directory. The system certificate store will be used by default. Falls back to the deprecated "capath" SSL context option if not specified.
  ca_file | string | Path to a certificate authority file. The system certificate store will be used by default. Falls back to the deprecated "cafile" SSL context option if not specified.
  crl_file | string | Path to a certificate revocation list file.
  pem_file | string | Path to a PEM encoded certificate to use for client authentication. Falls back to the deprecated "local_cert" SSL context option if not specified.
  pem_pwd | string | Passphrase for the PEM encoded certificate (if applicable). Falls back to the deprecated "passphrase" SSL context option if not specified.
  context | resource | SSL context options to be used as fallbacks for other driver options (as specified). Note that the driver does not consult the default stream context. This option is supported for backwards compatibility, but should be considered deprecated.
  weak_cert_validation | boolean | Disables certificate validation if `TRUE`. Defaults to `FALSE` Falls back to the deprecated "allow_self_signed" SSL context option if not specified.

### エラー / 例外

- 引数のパースに失敗した場合に MongoDB\Driver\Exception\InvalidArgumentException をスローします。
- Throws MongoDB\Driver\Exception\RuntimeException if the `uri` format is invalid

### 変更履歴

バージョン | 説明
--- | ---
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.
1.4.0 | Added the "compressors", "retryWrites", and "zlibCompressionLevel" URI options.
1.3.0 | The `uriOptions` argument now accepts "authMechanism" and "authMechanismProperties" options. Previously, these options were only supported in the `uri` argument.
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.
1.1.0 | The `uri` argument is optional and defaults to "mongodb://localhost:27017/".

### 例

例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/mydatabase");
?>`

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/mydatabase");
?>`

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",
]
);
?>`

### 参考

- Connection handling and persistence
- » MongoDB Connection String Format