Upgrade Guide
On this page
Overview
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
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:
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:
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).