test no changes

Author: norareidy

source/upgrade.txt

@@ -0,0 +1,127 @@
+.. _php-upgrade:
+
+========================
+Upgrade Library Versions
+========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: compatibility, backwards compatibility
+   :description: Learn how to upgrade the MongoDB PHP Library and PHP extension, ensuring compatibility and addressing breaking changes.
+
+Overview
+--------
+
+In this guide, you can learn about the changes you must make to your application
+when you upgrade to a new version of the {+php-library+}. This page also describes
+how to upgrade your {+extension-short+} to a new version.
+
+How to Upgrade
+--------------
+
+Before you upgrade, perform the following actions:
+
+- Ensure the new {+library-short+} version is compatible with the {+mdb-server+} versions
+  your application connects to and the PHP version your
+  application compiles with. For version compatibility information, see the
+  :ref:`{+php-library+} Compatibility <php-compatibility>`
+  page.
+- Address any breaking changes between the library version
+  your application is using and your planned upgrade version in the
+  :ref:`Breaking Changes <php-breaking-changes>` section.
+
+.. tip::
+
+   To ensure compatibility across {+mdb-server+} versions when
+   upgrading library versions, use the :ref:`{+stable-api+} <php-stable-api>`.
+
+Major and minor versions of the PHP extension and library are in sync. This
+means you can run an upgrade command for the extension to also upgrade the PHP 
+library. 
+
+Patch versions (x.x.x) for the library and extension are not in sync. Run the 
+respective commands to update to the patch versions for the library or extension. 
+
+To upgrade the PHP extension, replace ``<version-number>`` with the version number 
+you want to upgrade to and run the following command in your application's 
+directory:
+
+.. code-block:: bash
+
+   pecl upgrade mongodb-<version-number>
+
+To upgrade the PHP library version, replace ``<version-number>`` with the 
+version number you want to upgrade to and run the following command in your 
+application's directory:
+
+.. code-block:: bash
+
+   composer require mongodb/mongodb:<version-number>
+
+Detailed installation instructions may be found in the 
+:php:`PHP.net documentation <mongodb.installation>`.
+
+.. _php-breaking-changes:
+
+Breaking Changes
+----------------
+
+A breaking change is a change of a convention or a behavior starting in
+a specific version of the library. This type of change may prevent your
+application from working properly if not addressed before upgrading the
+library.
+
+The breaking changes in this section are categorized by the library
+version that introduced them. When upgrading library versions, address
+all the breaking changes between the current and upgrade versions.
+
+For more information on release changes, see the release notes and
+associated JIRA tickets for each release on `GitHub
+<https://github.com/mongodb/mongo-php-library/releases>`__.
+
+.. _php-v2-breaking-changes:
+
+Version 2.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library version 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()``
+
+  The ``MongoDB\\Database::createEncryptedCollection()`` method returns
+  the list of encrypted fields instead of the raw command response.
+
+  If there is an error, the methods throw an exception.
+
+  If you must access the raw command response from the preceding
+  methods, you can register a :php:`CommandSubscriber
+  <mongodb-driver-monitoring-commandsubscriber>` in your application.
+
+Version 1.20 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This library version introduces the following breaking changes:
+
+- Drops support for {+mdb-server+} 3.6.
+
+Version 1.19 and Earlier
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For library versions 1.19 and earlier, see the release notes and associated 
+JIRA tickets for each release on `GitHub <https://github.com/mongodb/mongo-php-library/releases>`__.