1. class
  2. MongoDB
  3. \
  4. Driver
  5. \
  6. Manager

Manager

final class Manager (View source)

The MongoDB\Driver\Manager is the main entry point to the extension. It is responsible for maintaining connections to MongoDB (be it standalone server, replica set, or sharded cluster).

No connection to MongoDB is made upon instantiating the Manager. This means the MongoDB\Driver\Manager can always be constructed, even though one or more MongoDB servers are down. Any write or query can throw connection exceptions as connections are created lazily. A MongoDB server may also become unavailable during the life time of the script. It is therefore important that all actions on the Manager to be wrapped in try/catch statements.

Methods

__construct(string|null $uri = null, array|null $uriOptions = null, array|null $driverOptions = null)

Manager constructor.

__wakeup()

No description

ClientEncryption
createClientEncryption(array $options)

Return a ClientEncryption instance.

WriteResult
executeBulkWrite(string $namespace, BulkWrite $bulk, array|null $options = null)

Execute one or more write operations

BulkWriteCommandResult
executeBulkWriteCommand(BulkWriteCommand $bulkWriteCommand, array|null $options = null)

Execute write operations using the bulkWrite command

CursorInterface
executeCommand(string $db, Command $command, array|null $options = null)

No description

CursorInterface
executeQuery(string $namespace, Query $query, array|null $options = null)

Execute a MongoDB query

CursorInterface
executeReadCommand(string $db, Command $command, array|null $options = null)

No description

CursorInterface
executeReadWriteCommand(string $db, Command $command, array|null $options = null)

No description

CursorInterface
executeWriteCommand(string $db, Command $command, array|null $options = null)

No description

array|object|null
getEncryptedFieldsMap()

Return the encryptedFieldsMap auto encryption option for the Manager

ReadConcern
getReadConcern()

Return the ReadConcern for the Manager

ReadPreference
getReadPreference()

Return the ReadPreference for the Manager

array
getServers()

Return the servers to which this manager is connected

WriteConcern
getWriteConcern()

Return the WriteConcern for the Manager

Server
selectServer(ReadPreference|null $readPreference = null)

Preselect a MongoDB node based on provided readPreference. This can be useful to guarantee a command runs on a specific server when operating in a mixed version cluster.

Session
startSession(array|null $options = null)

Start a new client session for use with this client

void
addSubscriber(Subscriber $subscriber)

Registers a monitoring event subscriber with this Manager

void
removeSubscriber(Subscriber $subscriber)

Unregisters a monitoring event subscriber with this Manager

Details

at line 32
final __construct(string|null $uri = null, array|null $uriOptions = null, array|null $driverOptions = null)

Manager constructor.

Parameters

string|null $uri

A mongodb:// connection URI
array|null $uriOptions

Connection string options
array|null $driverOptions

Any driver-specific options not included in MongoDB connection spec.

Exceptions

InvalidArgumentException
RuntimeException

at line 34
final __wakeup()

No description

at line 66
final ClientEncryption createClientEncryption(array $options)

Return a ClientEncryption instance.

Parameters

array $options

options 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. This option is required. kmsProviders array A document containing the configuration for one or more KMS providers, which are used to encrypt data keys. Supported providers include "aws", "azure", "gcp", "kmip", and "local" and at least one must be specified. If an empty document is specified for "aws", "azure", or "gcp", the driver will attempt to configure the provider using Automatic Credentials. The format for "aws" is as follows: aws: { accessKeyId: , secretAccessKey: , sessionToken: <optional string> } The format for "azure" is as follows: azure: { tenantId: , clientId:

, clientSecret: , identityPlatformEndpoint: // Defaults to "login.microsoftonline.com" } The format for "gcp" is as follows: gcp: { email: , privateKey: |, endpoint: // Defaults to "oauth2.googleapis.com" } The format for "kmip" is as follows: kmip: { endpoint: } The format for "local" is as follows: local: { // 96-byte master key used to encrypt/decrypt data keys key: | } tlsOptions array A document containing the TLS configuration for one or more KMS providers. Supported providers include "aws", "azure", "gcp", and "kmip". All providers support the following options: : { tlsCaFile: , tlsCertificateKeyFile: , tlsCertificateKeyFilePassword: , tlsDisableOCSPEndpointCheck: }

Return Value

ClientEncryption

Returns a new MongoDB\Driver\ClientEncryption instance.

Exceptions

InvalidArgumentException
RuntimeException

at line 81
final WriteResult executeBulkWrite(string $namespace, BulkWrite $bulk, array|null $options = null)

Since: 1.4.0 added $options argument

Execute one or more write operations

Parameters

string $namespace

A fully qualified namespace (databaseName.collectionName)
BulkWrite $bulk

The MongoDB\Driver\BulkWrite to execute.
array|null $options

WriteConcern type for backwards compatibility

Return Value

WriteResult

Exceptions

InvalidArgumentException
ConnectionException
AuthenticationException
BulkWriteException
RuntimeException

at line 98
final BulkWriteCommandResult executeBulkWriteCommand(BulkWriteCommand $bulkWriteCommand, array|null $options = null)

Since: 2.1.0

Execute write operations using the bulkWrite command

Parameters

BulkWriteCommand $bulkWriteCommand

The write(s) to execute.
array|null $options

options Option Type Description session MongoDB\Driver\Session A session to associate with the operation. writeConcern MongoDB\Driver\WriteConcern A write concern to apply to the operation.

Return Value

BulkWriteCommandResult

Returns MongoDB\Driver\BulkWriteCommandResult on success.

Exceptions

BulkWriteCommandException
InvalidArgumentException
ConnectionException
AuthenticationException
RuntimeException

at line 113
final CursorInterface executeCommand(string $db, Command $command, array|null $options = null)

Since: 1.4.0 added $options argument

No description

Parameters

string $db

The name of the database on which to execute the command.
Command $command

The command document.
array|null $options

ReadPreference type for backwards compatibility

Return Value

CursorInterface

Exceptions

Exception
AuthenticationException
ConnectionException
RuntimeException
BulkWriteException
WriteConcernException

at line 127
final CursorInterface executeQuery(string $namespace, Query $query, array|null $options = null)

Since: 1.4.0 added $options argument

Execute a MongoDB query

Parameters

string $namespace

A fully qualified namespace (databaseName.collectionName)
Query $query

A MongoDB\Driver\Query to execute.
array|null $options

ReadPreference type for backwards compatibility

Return Value

CursorInterface

Exceptions

Exception
AuthenticationException
ConnectionException
RuntimeException

at line 150
final CursorInterface executeReadCommand(string $db, Command $command, array|null $options = null)

Since: 1.4.0

No description

Parameters

string $db

The name of the database on which to execute the command that reads.
Command $command

The command document.
array|null $options

options Option Type Description readConcern MongoDB\Driver\ReadConcern A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version. readPreference MongoDB\Driver\ReadPreference A read preference to use for selecting a server for the operation. session MongoDB\Driver\Session A session to associate with the operation. If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction.

Return Value

CursorInterface

Exceptions

Exception
AuthenticationException
ConnectionException
RuntimeException
BulkWriteException
WriteConcernException

at line 173
final CursorInterface executeReadWriteCommand(string $db, Command $command, array|null $options = null)

Since: 1.4.0

No description

Parameters

string $db

The name of the database on which to execute the command that reads.
Command $command

The command document.
array|null $options

options Option Type Description readConcern MongoDB\Driver\ReadConcern A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version. session MongoDB\Driver\Session A session to associate with the operation. writeConcern MongoDB\Driver\WriteConcern A write concern to apply to the operation. If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction.

Return Value

CursorInterface

Exceptions

Exception
AuthenticationException
ConnectionException
RuntimeException
BulkWriteException
WriteConcernException

at line 193
final CursorInterface executeWriteCommand(string $db, Command $command, array|null $options = null)

Since: 1.4.0

No description

Parameters

string $db

The name of the database on which to execute the command that writes.
Command $command

The command document.
array|null $options

options Option Type Description session MongoDB\Driver\Session A session to associate with the operation. writeConcern MongoDB\Driver\WriteConcern A write concern to apply to the operation. If you are using a "session" which has a transaction in progress, you cannot specify a "readConcern" or "writeConcern" option. This will result in an MongoDB\Driver\Exception\InvalidArgumentException being thrown. Instead, you should set these two options when you create the transaction with MongoDB\Driver\Session::startTransaction.

Return Value

CursorInterface

Exceptions

Exception
AuthenticationException
ConnectionException
RuntimeException
BulkWriteException
WriteConcernException

at line 200
final array|object|null getEncryptedFieldsMap()

Since: 1.14.0

Return the encryptedFieldsMap auto encryption option for the Manager

Return Value

array|object|null

at line 207
final ReadConcern getReadConcern()

Return the ReadConcern for the Manager

Return Value

ReadConcern

Exceptions

InvalidArgumentException

at line 215
final ReadPreference getReadPreference()

Return the ReadPreference for the Manager

Return Value

ReadPreference

The MongoDB\Driver\ReadPreference for the Manager.

Exceptions

InvalidArgumentException

at line 224
final array getServers()

Return the servers to which this manager is connected

Return Value

array

Returns an array of MongoDB\Driver\Server instances to which this manager is connected.

Exceptions

InvalidArgumentException

at line 232
final WriteConcern getWriteConcern()

Return the WriteConcern for the Manager

Return Value

WriteConcern

The MongoDB\Driver\WriteConcern for the Manager.

Exceptions

InvalidArgumentException

at line 244
final Server selectServer(ReadPreference|null $readPreference = null)

Preselect a MongoDB node based on provided readPreference. This can be useful to guarantee a command runs on a specific server when operating in a mixed version cluster.

https://secure.php.net/manual/en/mongodb-driver-manager.selectserver.php

Parameters

ReadPreference|null $readPreference

Optionally, a MongoDB\Driver\ReadPreference to route the command to. If none given, defaults to the Read Preferences set by the MongoDB Connection URI.

Return Value

Server

Returns a MongoDB\Driver\Server matching the read preference.

Exceptions

InvalidArgumentException
ConnectionException
AuthenticationException
RuntimeException

at line 276
final Session startSession(array|null $options = null)

Since: 1.4.0

Start a new client session for use with this client

Parameters

array|null $options

options Option Type Description Default causalConsistency bool Configure causal consistency in a session. If true, each operation in the session will be causally ordered after the previous read or write operation. Set to false to disable causal consistency. See Causal Consistency in the MongoDB manual for more information. true defaultTransactionOptions array Default options to apply to newly created transactions. These options are used unless they are overridden when a transaction is started with different value for each option. options Option Type Description maxCommitTimeMS integer The maximum amount of time in milliseconds to allow a single commitTransaction command to run. If specified, maxCommitTimeMS must be a signed 32-bit integer greater than or equal to zero. readConcern MongoDB\Driver\ReadConcern A read concern to apply to the operation. This option is available in MongoDB 3.2+ and will result in an exception at execution time if specified for an older server version. readPreference MongoDB\Driver\ReadPreference A read preference to use for selecting a server for the operation. writeConcern MongoDB\Driver\WriteConcern A write concern to apply to the operation. This option is available in MongoDB 4.0+. [] snapshot bool Configure snapshot reads in a session. If true, a timestamp will be obtained from the first supported read operation in the session (i.e. find, aggregate, or unsharded distinct). Subsequent read operations within the session will then utilize a "snapshot" read concern level to read majority-committed data from that timestamp. Set to false to disable snapshot reads. Snapshot reads require MongoDB 5.0+ and cannot be used with causal consistency, transactions, or write operations. If "snapshot" is true, "causalConsistency" will default to false. See Read Concern "snapshot" in the MongoDB manual for more information. false

Return Value

Session

Returns a MongoDB\Driver\Session.

Exceptions

InvalidArgumentException
RuntimeException

at line 283
final void addSubscriber(Subscriber $subscriber)

Since: 1.10.0

Registers a monitoring event subscriber with this Manager

Parameters

Subscriber $subscriber

Return Value

void

at line 290
final void removeSubscriber(Subscriber $subscriber)

Since: 1.10.0

Unregisters a monitoring event subscriber with this Manager

Parameters

Subscriber $subscriber

Return Value

void