Release Notes

What's New in 2.1

The PHP library v2.1 release includes the following features, improvements, and fixes:

• Adds compatibility with PHP 8.5.

• Adds a client bulk write API to perform write operations on multiple databases and collections in the same call. To learn more about this feature, see the Client Bulk Write section of the Bulk Write Operations guide.

What's New in 2.0

The PHP library v2.0 release includes the following API changes and removals:

• Adds the following methods:

  • MongoDB\Client::getDatabase(): alias for MongoDB\Client::selectDatabase()

  • MongoDB\Client::getCollection(): alias for MongoDB\Client::selectCollection()

  • MongoDB\Database::getCollection(): alias for MongoDB\Database::selectCollection()

  The Client::selectCollection(), Client::selectDatabase(), and Database::selectCollection() methods will be deprecated and replaced by these new methods in a future driver release, so consider changing the usages in your application.

• Modifies the MongoDB\Database::aggregate() and MongoDB\Collection::aggregate() methods so they can accept a Pipeline instance as the $pipeline parameter. To view examples that use this construction, see the Aggregation Builder section of the Aggregation guide.

• Replaces Cursor type hints with CursorInterface for better extensibility and compatibility.

• Removes deprecated fields in GridFS types.

  • The library does not calculate the md5 field when a file is uploaded to GridFS. If your application requires a file digest, you must implement this process outside GridFS and store the values in metadata.

  • The fields contentType and aliases are no longer stored in the files GridFS collection. If your application requires this information, you must store it in metadata. To learn more about GridFS, see the Store Large Files guide.

• Removes the following deprecated options for find operations:

  • maxScan

  • modifiers

  • oplogReplay

  • snapshot

  To learn about supported options for find operations, see the MongoDB\Collection::find() or MongoDB\Collection::findOne() API documentation.

• Removes the deprecated IndexInfo::isGeoHaystack() method.

• Removes the deprecated autoIndexId and flags options for the MongoDB\Database::createCollection() method.

• Drops support for map-reduce functionality by removing the following deprecated methods and types:

  • MongoDB\Collection::mapReduce()

  • MongoDB\MapReduceResult

  You can rewrite map-reduce operations by using aggregation pipeline stages such as $group and $merge. To learn more, see Map-Reduce to Aggregation Pipeline in the MongoDB Server manual.

• Removes the following Iterator implementations:

  • MongoDB\Model\CollectionInfoIterator

  • MongoDB\Model\DatabaseInfoIterator

  • MongoDB\Model\IndexInfoIterator

  The MongoDB\Client::listDatabases(), MongoDB\Database::listCollections(), and MongoDB\Collection::listIndexes() methods return a general traversable Iterator instance that provides the corresponding results.

What's New in 1.21

The PHP library v1.21 release includes the following features, improvements, and fixes:

• Introduces the Aggregation Builder, an API to build aggregation pipelines in a more type-safe way. To learn more and view examples, see the Aggregation Builder section of the Aggregation guide.

• Adds the following methods:

  • MongoDB\Client::getDatabase(): alias for MongoDB\Client::selectDatabase()

  • MongoDB\Database::getCollection(): alias for MongoDB\Database::selectCollection()

  • MongoDB\Database::getCollection(): alias for MongoDB\Database::selectCollection()

  The Client::selectCollection(), Client::selectDatabase(), and Database::selectCollection() methods will be deprecated and replaced by these new methods in a future driver release, so consider changing the usages in your application.

• Adds named arguments for the SearchStage, VectorSearchStage, and SearchMetaStage builder classes. This change allows you to write MongoDB Search and MongoDB Vector Search queries in a more type-safe and organized way. To learn more, see the Run a MongoDB Search Query and Run a MongoDB Vector Search Query guides.

• Deprecates the flags option, used for the deprecated MMAPv1 storage engine. This option will be removed in PHP library v2.0.

• Adds a sort option to the MongoDB\Collection::updateOne() and MongoDB\Collection::replaceOne() methods. This change also allows you to set a sort order as an option when performing update and replace operations in a bulk operation.

• Adds the builderEncoder option to the following methods:

  • Database constructor

  • MongoDB\Database::withOptions()

  • Collection constructor

  • MongoDB\Collection::withOptions()

For more information about the changes in this version, see the v1.21 release notes on GitHub.

What's New in 1.20

• Adds support for MongoDB Server v8.0.

• Adds support for Queryable Encryption (QE) range queries. To use this feature, your app must connect to MongoDB Server 8.0 or later. For more information about QE range queries, see Queryable Encryption in the MongoDB Server manual.

• When a sharded cluster operation is unsuccessful, the library avoids selecting the same mongos server for operation retry attempts if other mongos servers are available.

• When you create a KMIP data key, you can now specify the delegated option. If this option is set to true, the KMIP provider performs encryption and decryption of the data key locally, ensuring that the encryption key never leaves the KMIP server.

• Adds the type option in Search index specifications for the MongoDB\Collection::createIndex() and MongoDB\Collection::createSearchIndexes() methods. This change allows you to create MongoDB Vector Search indexes programmatically. To learn more and view examples, see the MongoDB Search Indexes guide.

For more information about the changes in this version, see the v1.20 release notes on GitHub.

What's New in 1.19

This release of the PHP library contains no significant changes and was added to keep version parity with the PHP extension.

What's New in 1.18

• Adds a new GridFS API to make it more convenient to work with files using PHP's existing filesystem functions. The MongoDB\GridFS\Bucket::registerGlobalStreamWrapperAlias() method may be used to register a global alias for a GridFS bucket. After doing so, files within that bucket can be accessed by using only a file URI (e.g. "gridfs://mybucket/hello.txt"). A demonstration of this API can be found in the gridfs_stream_wrapper.php example script.

• Adds MongoDB\Client::addSubscriber() and MongoDB\Client::removeSubscriber() methods to the MongoDB\Client class to make it easier to register monitoring classes scoped to the underlying MongoDB\Driver\Manager object.

To learn more about this release, see the v1.18 Release Notes on GitHub.

What's New in 1.17

• Introduces a new "codec" API for converting BSON to and from PHP objects. More information on this feature may be found in the Codecs tutorial.

• Adds MongoDB\add_logger() and MongoDB\remove_logger() functions to the library. These functions allow applications to register a PSR-3 Logger to receive log messages emitted by the driver. Previously, logs were only available through the extension's mongodb.debug INI setting.

• Introduces new MongoDB\Collection methods to create and manage MongoDB Search indexes. MongoDB Search indexes can be queried using the $search aggregation pipeline stage, which is supported in all versions of the library. To learn more about MongoDB Search indexes and the specifics of the $search aggregation stage, see the MongoDB Search indexes documentation and $search.

• Upgrades the mongodb extension requirement to 1.17.0. Support for PHP 7.2 and 7.3 has been removed and the library now requires PHP 7.4 or newer.

To learn more about this release, see the v1.17 Release Notes on GitHub.