Upgrade Guide


The MongoDB PHP Library and underlying mongodb extension have notable API differences from the legacy mongo extension. This page will summarize those differences for the benefit of those upgrading from the legacy driver.

Additionally, a community-developed mongo-php-adapter library exists, which implements the mongo extension API using this library and the new driver. While this adapter library is not officially supported by MongoDB, it does bear mentioning.

Collection API

This library’s MongoDB\Collection class implements MongoDB’s cross-driver CRUD and Index Management specifications. Although some method names have changed in accordance with the new specifications, the new class provides the same functionality as the legacy driver’s MongoCollection class with some notable exceptions.

Old and New Methods

MongoCollection MongoDB\Collection
MongoCollection::aggregate() MongoDB\Collection::aggregate()
MongoCollection::aggregateCursor() MongoDB\Collection::aggregate()
MongoCollection::batchInsert() MongoDB\Collection::insertMany()
MongoCollection::count() MongoDB\Collection::count()
MongoCollection::createDBRef() Not yet implemented. See PHPLIB-24.
MongoCollection::createIndex() MongoDB\Collection::createIndex()
MongoCollection::deleteIndex() MongoDB\Collection::dropIndex()
MongoCollection::deleteIndexes() MongoDB\Collection::dropIndexes()
MongoCollection::drop() MongoDB\Collection::drop()
MongoCollection::distinct() MongoDB\Collection::distinct()
MongoCollection::ensureIndex() MongoDB\Collection::createIndex()
MongoCollection::find() MongoDB\Collection::find()
MongoCollection::findAndModify() MongoDB\Collection::findOneAndDelete(), MongoDB\Collection::findOneAndReplace(), and MongoDB\Collection::findOneAndUpdate()
MongoCollection::findOne() MongoDB\Collection::findOne()
MongoCollection::getDBRef() Not implemented. See PHPLIB-24.
MongoCollection::getIndexInfo() MongoDB\Collection::listIndexes()
MongoCollection::getName() MongoDB\Collection::getCollectionName()
MongoCollection::getReadPreference() Not implemented.
MongoCollection::getSlaveOkay() Not implemented.
MongoCollection::getWriteConcern() Not implemented.
MongoCollection::group() Not yet implemented. See PHPLIB-177. Use MongoDB\Database::command().
MongoCollection::insert() MongoDB\Collection::insertOne()
MongoCollection::parallelCollectionScan() Not implemented.
MongoCollection::remove() MongoDB\Collection::deleteMany() and MongoDB\Collection::deleteOne()
MongoCollection::save() MongoDB\Collection::insertOne() or MongoDB\Collection::replaceOne() with the upsert option.
MongoCollection::setReadPreference() Not implemented. Use MongoDB\Collection::withOptions()
MongoCollection::setSlaveOkay() Not implemented.
MongoCollection::setWriteConcern() Not implemented. Use MongoDB\Collection::withOptions()
MongoCollection::update() MongoDB\Collection::replaceOne(), MongoDB\Collection::updateMany(), and MongoDB\Collection::updateOne().
MongoCollection::validate() Not implemented.

A guiding principle in designing the new APIs was that explicit method names are preferable to overloaded terms found in the old API. For instance, MongoCollection::save() and MongoCollection::findAndModify() have different modes of operation, depending on their arguments. Methods were also split to distinguish between updating specific fields and full-document replacement.

Group Command Helper

MongoDB\Collection does not yet have a helper method for the group command; however, it is planned in PHPLIB-177. The following example demonstrates how to execute a group command using the MongoDB\Database::command() method:


$database = (new MongoDB\Client)->selectDatabase('db_name');
$cursor = $database->command([
    'group' => [
        'ns' => 'collection_name',
        'key' => ['field_name' => 1],
        'initial' => ['total' => 0],
        '$reduce' => new MongoDB\BSON\Javascript('...'),

$resultDocument = $cursor->toArray()[0];

MapReduce Command Helper

MongoDB\Collection does not yet have a helper method for the mapReduce command; however, that is planned in PHPLIB-53. The following example demonstrates how to execute a mapReduce command using the MongoDB\Database::command() method:


$database = (new MongoDB\Client)->selectDatabase('db_name');
$cursor = $database->command([
    'mapReduce' => 'collection_name',
    'map' => new MongoDB\BSON\Javascript('...'),
    'reduce' => new MongoDB\BSON\Javascript('...'),
    'out' => 'output_collection_name',

$resultDocument = $cursor->toArray()[0];

DBRef Helpers

MongoDB\Collection does not yet have helper methods for working with DBRef objects; however, that is planned in PHPLIB-24.

MongoCollection::save() Removed

MongoCollection::save(), which was syntactic sugar for an insert or upsert operation, has been removed in favor of explicitly using MongoDB\Collection::insertOne or MongoDB\Collection::replaceOne (with the upsert option).

While the save method does have its uses for interactive environments, such as the mongo shell, it was intentionally excluded from the CRUD specification for language drivers. Generally, application code should know if the document has an identifier and be able to explicitly insert or replace the document and handle the returned MongoDB\InsertOneResult or MongoDB\UpdateResult, respectively. This also helps avoid inadvertent and potentially dangerous full-document replacements.

Accessing IDs of Inserted Documents

In the legacy driver, MongoCollection::insert(), MongoCollection::batchInsert(), and MongoCollection::save() (when inserting) would modify their input argument by injecting an _id key with a generated ObjectId (i.e. MongoId object). This behavior was a bit of a hack, as it did not rely on the argument being passed by reference; instead, it directly modified memory through the extension API and could not be implemented in PHP userland. As such, it is no longer done in the new driver and library.

IDs of inserted documents (whether generated or not) may be accessed through the following methods on the write result objects:

Bulk Write Operations

The legacy driver’s MongoWriteBatch classes have been replaced with a general-purpose MongoDB\Collection::bulkWrite() method. Whereas the legacy driver only allowed bulk operations of the same type, the new method allows operations to be mixed (e.g. inserts, updates, and deletes).

←   Example Data Reference  →