whats-new.txt

.. _php-lib-whats-new:

==========
What's New
==========

.. facet::
   :name: genre
   :values: reference

.. meta::
   :keywords: update, new feature, deprecation, upgrade

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Learn about new features, improvements, and fixes introduced in the
following versions of the {+php-library+}:

* :ref:`Version 2.0 <php-lib-version-2.0>`
* :ref:`Version 1.21 <php-lib-version-1.21>`
* :ref:`Version 1.20 <php-lib-version-1.20>`
* :ref:`Version 1.19 <php-lib-version-1.19>`
* :ref:`Version 1.18 <php-lib-version-1.18>`
* :ref:`Version 1.17 <php-lib-version-1.17>`

.. _php-lib-version-2.0:

What's New in 2.0
-----------------

.. important:: Breaking Changes

   The {+library-short+} v2.0 release introduces the following breaking
   changes:

   - The following methods return ``void`` instead of the raw command
     response:
   
     - ``MongoDB\Client``: ``dropDatabase()``
     - ``MongoDB\Collection``: ``drop()``, ``dropIndex()``,
       ``dropIndexes()``, ``dropSearchIndex()``, ``rename()``
     - ``MongoDB\Database``: ``createCollection()``, ``drop()``,
       ``dropCollection()``, ``renameCollection()``
   
   To learn more about breaking changes in this release, see the
   :ref:`Version 2.0 Breaking Changes <php-v2-breaking-changes>` section
   in the Upgrade Library Versions guide.

The {+library-short+} v2.0 release includes the following API changes
and removals:

- Adds the following methods:

  - :phpmethod:`MongoDB\Client::getDatabase()`: alias for :phpmethod:`MongoDB\Client::selectDatabase()`
  - :phpmethod:`MongoDB\Client::getCollection()`: alias for :phpmethod:`MongoDB\Client::selectCollection()`
  - :phpmethod:`MongoDB\Database::getCollection()`: alias for :phpmethod:`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 :phpmethod:`MongoDB\Database::aggregate()` and
  :phpmethod:`MongoDB\Collection::aggregate()` methods so they can
  accept a ``Pipeline`` instance as the ``$pipeline`` parameter. To view
  examples that use this construction, see the
  :ref:`php-aggregation-builder-api` section of the Aggregation guide.

- 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 :ref:`php-gridfs` guide.

- Removes the following deprecated options for find operations:

  - ``maxScan``
  - ``modifiers``
  - ``oplogReplay``
  - ``snapshot``

  To learn about supported options for find operations, see the
  :phpmethod:`MongoDB\Collection::find()` or
  :phpmethod:`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
  :manual:`Map-Reduce to Aggregation Pipeline
  </reference/map-reduce-to-aggregation-pipeline/>` in the
  {+mdb-server+} manual.

- Removes the following ``Iterator`` implementations:

  - ``MongoDB\Model\CollectionInfoIterator``
  - ``MongoDB\Model\DatabaseInfoIterator``
  - ``MongoDB\Model\IndexInfoIterator``

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

.. _php-lib-version-1.21:

What's New in 1.21
------------------

The {+library-short+} 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 :ref:`php-aggregation-builder-api` section of
  the Aggregation guide.

- Adds the following methods:

  - :phpmethod:`MongoDB\Client::getDatabase()`: alias for :phpmethod:`MongoDB\Client::selectDatabase()`
  - :phpmethod:`MongoDB\Database::getCollection()`: alias for :phpmethod:`MongoDB\Database::selectCollection()`
  - :phpmethod:`MongoDB\Database::getCollection()`: alias for :phpmethod:`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 Atlas Search and Atlas Vector Search queries in a
  more type-safe and organized way. To learn more, see the
  :ref:`php-atlas-search` and :ref:`php-vector-search` guides.

- Deprecates the ``flags`` option, used for the deprecated MMAPv1 storage engine. 
  This option will be removed in {+library-short+} v2.0.

- Adds a sort option to the :phpmethod:`MongoDB\Collection::updateOne()`
  and :phpmethod:`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:

  - :phpmethod:`Database constructor <MongoDB\Database::__construct()>`
  - :phpmethod:`MongoDB\Database::withOptions()`
  - :phpmethod:`Collection constructor <MongoDB\Collection::__construct()>`  
  - :phpmethod:`MongoDB\Collection::withOptions()`

For more information about the changes in this version, see the
:github:`v1.21 release notes
</mongodb/mongo-php-library/releases/tag/1.21.0>` on GitHub.

.. _php-lib-version-1.20:

What's New in 1.20
------------------

.. important:: {+mdb-server+} v3.6 End-of-Life

   Support for {+mdb-server+} v3.6 is removed in this release of the
   library.

- Adds support for {+mdb-server+} v8.0.

- Adds support for Queryable Encryption (QE) range queries. To use this
  feature, your app must connect to {+mdb-server+} 8.0 or later. For
  more information about QE range queries, see :manual:`Queryable
  Encryption </core/queryable-encryption>` in the {+mdb-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 :phpmethod:`MongoDB\Collection::createIndex()` and
  :phpmethod:`MongoDB\Collection::createSearchIndexes()` methods. This
  change allows you to create Atlas Vector Search indexes
  programmatically. To learn more and view examples, see the
  :ref:`php-atlas-search-index` guide.

For more information about the changes in this version, see the
:github:`v1.20 release notes
</mongodb/mongo-php-library/releases/tag/1.20.0>` on GitHub.

.. _php-lib-version-1.19:

What's New in 1.19
------------------

This release of the {+library-short+} contains no significant changes
and was added to keep version parity with the {+extension-short+}.

.. _php-lib-version-1.18:

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 :phpmethod:`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 <https://github.com/mongodb/mongo-php-library/blob/1.18.0/examples/gridfs_stream_wrapper.php>`__ 
  example script.

- Adds :phpmethod:`MongoDB\Client::addSubscriber()` and 
  :phpmethod:`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 
<https://github.com/mongodb/mongo-php-library/releases/tag/1.18.0>`__ on GitHub.

.. _php-lib-version-1.17:

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 
  :ref:`Codecs tutorial <php-codecs>`.

- Adds :phpmethod:`MongoDB\add_logger()` and 
  :phpmethod:`MongoDB\remove_logger()` functions to the library. 
  These functions allow applications to register a `PSR-3 Logger <https://www.php-fig.org/psr/psr-3/>`__
  to receive log messages emitted by the driver. Previously, logs were only 
  available through the extension's `mongodb.debug <https://www.php.net/manual/en/mongodb.configuration.php#ini.mongodb.debug>`__ 
  ``INI`` setting.

- Introduces new :phpclass:`MongoDB\Collection` methods to create and manage 
  Atlas Search indexes. Atlas Search indexes can be queried using the ``$search`` 
  aggregation pipeline stage, which is supported in all versions of the library.
  To learn more about Atlas Search indexes and the specifics of the ``$search`` 
  aggregation stage, see the :atlas:`Atlas Search indexes </atlas-search>` 
  documentation and :manual:`$search </reference/operator/aggregation/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 
<https://github.com/mongodb/mongo-php-library/releases/tag/1.17.0>`__ on
GitHub.