Databases and Collections

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::getDatabase() method.

The following example accesses a database named test_database:

$db = $client->getDatabase('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 library API documentation
Magic Methods in the PHP manual

Access a Collection

Access a collection by using either of the following methods:

MongoDB\Client::getCollection(): Pass the database and collection names as parameters
MongoDB\Database::getCollection(): Pass the collection name as a parameter

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

$collection = $client->test_database->getCollection('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:

$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;
}

MongoDB\Model\CollectionInfo Object
(
 [name] => example_collection
 [type] => collection
 ...
)
MongoDB\Model\CollectionInfo Object
(
 [name] => test_collection
 [type] => collection
 ...
)

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 read and write operations run on replica sets by specifying a read preference, read concern, or 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 getCollection() method is called. You can change these settings by passing an options array to the MongoDB\Client::getDatabase(), MongoDB\Client::getCollection(), or MongoDB\Database::getCollection() methods.

To learn more about setting a read preference, read concern, and write concern, see the Specify How CRUD Operations Run on Replica Sets guide.

API Documentation

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

Back

Stable API

Time Series