Docs Menu
Docs Home
/
PHP Library Manual

Databases and Collections

On this page

  • Overview
  • Access a Database
  • Access a Collection
  • Create a Collection
  • Get a List of Collections
  • Delete a Collection
  • Configure Read and Write Operations
  • Database Configuration Example
  • Collection Configuration Example
  • Advanced Read Configurations
  • API Documentation

Overview

In this guide, you can learn how to use MongoDB databases and collections with the MongoDB PHP Library.

MongoDB organizes data into a hierarchy of the following levels:

  • Databases: Top-level data structures in a MongoDB deployment that store collections.

  • Collections: Groups of MongoDB documents. They are analogous to tables in relational databases.

  • Documents: Units that store literal data such as string, numbers, dates, and other embedded documents. For more information about document field types and structure, see the Documents guide in the MongoDB Server manual.

Access a Database

Access a database by passing the database name to the MongoDB\Client::selectDatabase() method.

The following example accesses a database named test_database:

$db = $client->selectDatabase('test_database');

Alternatively, you can implicitly call the MongoDB\Client::__get() magic method on a client object. This method allows you to select a database by using the syntax for accessing a class property. The following example uses this shorthand syntax to access the test_database database:

$db = $client->test_database;

Tip

To learn more about __get() and PHP magic methods, see the following resources:

  • MongoDB\Client::__get() in the API documentation

  • Magic Methods in the PHP manual

Access a Collection

Access a collection by using either of the following methods:

  • MongoDB\Client::selectCollection(): Pass the database and collection names as parameters

  • MongoDB\Database::selectCollection(): Pass the collection name as a parameter

The following example accesses a collection named test_collection by using the MongoDB\Database::selectCollection() method:

$collection = $client->test_database->selectCollection('test_collection');

Tip

If the provided collection name does not already exist in the database, MongoDB implicitly creates the collection when you first insert data into it.

Alternatively, you can implicitly call the MongoDB\Database::__get() magic method on a database object. This method allows you to select a collection by using the syntax for accessing a class property. The following example uses this shorthand syntax to access the test_collection collection:

$collection = $db->test_collection;

To learn more, see the MongoDB\Database::__get() API documentation.

Create a Collection

Pass a collection name to the MongoDB\Database::createCollection() method to explicitly create a collection in a MongoDB database.

The following example creates a collection named example_collection:

$result = $client->test_database->createCollection('example_collection');

You can specify collection options, such as maximum size and document validation rules, by passing them as an array to the createCollection() method. For a full list of optional parameters, see the API documentation.

Get a List of Collections

You can query for a list of collections in a database by calling the MongoDB\Database::listCollections() method. The method returns a cursor containing all collections in the database and their associated metadata.

The following example calls the listCollections() method and iterates over the returned iterator to print the collections from the Access a Collection and Create a Collection examples:

foreach ($client->test_database->listCollections() as $collectionInfo) {
    print_r($collectionInfo) . PHP_EOL;
}

Delete a Collection

You can delete a collection from the database by using the MongoDB\Database::dropCollection() method.

The following example deletes the test_collection collection:

$client->test_database->dropCollection('test_collection');

Warning

Dropping a Collection Deletes All Data in the Collection

Dropping a collection from your database permanently deletes all documents and all indexes within that collection.

Drop a collection only if you no longer need the data in it.

Configure Read and Write Operations

You can control how the library routes read operations by setting a read preference. You can also control options for how the library waits for acknowledgment of read and write operations on a replica set by setting a read concern and a write concern.

By default, databases inherit read and write settings from the MongoDB\Client instance. Collections inherit these settings from the MongoDB\Client or MongoDB\Database instance on which the selectCollection() method is called. You can change these settings by passing an options array to the MongoDB\Client::selectDatabase(), MongoDB\Client::selectCollection(), or MongoDB\Database::selectCollection() methods.

To change the read preference, read concern, and write concern of your database or collection, set the following options in the array parameter:

  • readPreference: Sets the read preference. For a list of available read preferences, see MongoDB\Driver\ReadPreference in the extension API documentation.

  • readConcern: Sets the read concern. For a list of available read concerns, see MongoDB\Driver\ReadConcern in the extension API documentation.

  • writeConcern: Sets the write concern. For a list of available write concerns, see MongoDB\Driver\WriteConcern in the extension API documentation.

Tip

To learn more about read preferences and read and write concerns, see the following guides in the MongoDB Server manual:

Database Configuration Example

The following 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 selectDatabase():

$readPreference = new ReadPreference(ReadPreference::RP_SECONDARY);
$readConcern = new ReadConcern(ReadConcern::LOCAL);
$writeConcern = new WriteConcern(WriteConcern::MAJORITY);
$db = $client->selectDatabase('test_database', [
    'readPreference' => $readPreference,
    'readConcern' => $readConcern,
    'writeConcern' => $writeConcern,
]);

Collection Configuration Example

The following 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 selectCollection():

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

Advanced Read Configurations

Tag Sets

In MongoDB Server, you can 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.

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->selectDatabase(
    'test_database',
    ['readPreference' => $readPreference],
);

Local Threshold

If multiple replica-set members match the read preference and tag sets you specify, the MongoDB PHP Library reads from the nearest replica-set members, chosen according to their ping time.

By default, the library uses only members whose ping times are within 15 milliseconds of the nearest member for queries. To distribute reads between members with higher latencies, pass an options array to the MongoDB\Client constructor that sets the localThresholdMS option.

The following example specifies a local threshold of 35 milliseconds:

$options = [
    'replicaSet' => 'repl0',
    'readPreference' => new ReadPreference(ReadPreference::RP_SECONDARY_PREFERRED),
    'localThresholdMS' => 35,
];
$client = new Client('<connection string>', [], $options);

In the preceding example, the MongoDB PHP Library distributes reads among matching members within 35 milliseconds of the closest member's ping time.

Note

The MongoDB PHP Library ignores the value of localThresholdMS when communicating with a replica set through a mongos instance. In this case, use the localThreshold command-line option.

API Documentation

To learn more about any of the methods or types discussed in this guide, see the following API documentation:

Back

Configure Transport Layer Security (TLS)