Configure CRUD Operations

Client Configuration

This example shows how to set the read preference, read concern, and write concern of a MongoDB\Client instance by passing an array to the constructor. The code configures the following settings:

• secondary read preference: Read operations retrieve data from secondary replica set members

• local read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• 2 write concern: The primary and one secondary replica set member must acknowledge the write operation

$clientOptions = [
    'readPreference' => 'secondary',
    'readConcernLevel' => 'local',
    'w' => '2',
];
$client = new Client('mongodb://localhost:27017', $clientOptions);

Alternatively, you can specify the read and write settings in the connection URI, which is passed as a parameter to the MongoDB\Client constructor:

$uri = 'mongodb://localhost:27017/?readPreference=secondary&readConcernLevel=local&w=2';
$client = new Client($uri);

Session Configuration

This example shows how to set the read preference, read concern, and write concern of a session by passing an array to the startSession() method. The code configures the following settings:

• PRIMARY_PREFERRED read preference: Read operations retrieve data from the primary replica set member, or secondary members if the primary is unavailable

• LOCAL read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• MAJORITY write concern: The majority of all replica set members must acknowledge the write operation

$sessionOptions = [
    'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
    'readConcern' => new ReadConcern(ReadConcern::LOCAL),
    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
];
$session = $client->startSession($sessionOptions);

Transaction Configuration

This example shows how to set the read preference, read concern, and write concern of a transaction by passing an array to the startTransaction() method. The code configures the following settings:

• PRIMARY read preference: Read operations retrieve data from the primary replica set member

• MAJORITY read concern: Read operations return the instance's most recent data that has been written to a majority of replica set members

• 1 write concern: The primary replica set member must acknowledge the write operation

$transactionOptions = [
    'readPreference' => new ReadPreference(ReadPreference::PRIMARY),
    'readConcern' => new ReadConcern(ReadConcern::MAJORITY),
    'writeConcern' => new WriteConcern(1),
];
$session->startTransaction($transactionOptions);

Database Configuration

This example shows how to set the read preference, read concern, and write concern of a database called test_database by passing an options array to the getDatabase() method. The code configures the following settings:

• PRIMARY_PREFERRED read preference: Read operations retrieve data from the primary replica set member, or secondary members if the primary is unavailable

• AVAILABLE read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• MAJORITY write concern: The majority of all replica set members must acknowledge the write operation

$db = $client->getDatabase('test_database', [
    'readPreference' => new ReadPreference(ReadPreference::PRIMARY_PREFERRED),
    'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
    'writeConcern' => new WriteConcern(WriteConcern::MAJORITY),
]);

Collection Configuration

This example shows how to set the read preference, read concern, and write concern of a collection called test_collection by passing an options array to the getCollection() method. The code configures the following settings:

• SECONDARY_PREFERRED read preference: Read operations retrieve data from secondary replica set members, or the primary members if no secondaries are available

• AVAILABLE read concern: Read operations return the instance's most recent data without guaranteeing that the data has been written to a majority of the replica set members

• 0 write concern: Requests no acknowledgment of the write operation

$collection = $client->getCollection('test_database', 'test_collection', [
    'readPreference' => new ReadPreference(ReadPreference::SECONDARY_PREFERRED),
    'readConcern' => new ReadConcern(ReadConcern::AVAILABLE),
    'writeConcern' => new WriteConcern(0),
]);

Tag Sets

The MongoDB Server allows you to apply key-value tags to replica-set members according to any criteria you choose. You can then use those tags to target one or more members for a read operation.

By default, the MongoDB PHP Library ignores tags when choosing a member to read from. To instruct the MongoDB PHP Library to prefer certain tags, pass them as a parameter to your MongoDB\Driver\ReadPreference class constructor. Then, set the MongoDB\Driver\ReadPreference object as the value of the readPreference database option.

Suppose you are connected to a replica set that contains members hosted at multiple data centers across the United States. This code example sets the readPreference option to a tag set that instructs test_database to prefer reads from secondary replica set members in the following order:

1. Members from the New York data center (['dc' => 'ny'])

2. Members from the San Francisco data center (['dc' => 'sf'])

3. Any secondary members ([])

$readPreference = new ReadPreference(
    ReadPreference::RP_SECONDARY,
    [
        ['dc' => 'ny'],
        ['dc' => 'sf'],
        [],
    ],
);
$db = $client->getDatabase(
    'test_database',
    ['readPreference' => $readPreference],
);

Load Balancing

When connecting to a sharded cluster or a replica set, the PHP library uses load balancing to handle read and write requests. Load balancing allows the library to distribute these requests across multiple servers to avoid overwhelming any one server and ensure optimal performance.

When connecting to a sharded cluster, the PHP library determines the closest mongos instance by calculating which one has the lowest network round-trip time. Then, the library determines the latency window by adding this mongos's average round-trip time to the localThresholdMS value. The library load balances requests across up to two random mongos instances that fall within the latency window. For each request, the library chooses the server with the lower operation load by determining its operationCount value.

When connecting to a replica set, the PHP library first selects replica set members according to your read preference. Then, the library follows the same process as described in the preceding paragraph. After calculating the latency window, the library selects up to two random replica set members that fall within the window and chooses the member with the lower operationCount value to receive the request.

$options = [
    'replicaSet' => 'repl0',
    'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED),
    'localThresholdMS' => 35,
];
$client = new Client('mongodb://localhost:27017', [], $options);