diff --git a/snooty.toml b/snooty.toml index dcccdff7..e405fe5f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -28,7 +28,8 @@ toc_landing_pages = [ "/write", "/indexes", "/security", - "/data-formats" + "/data-formats", + "/upgrade" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/index.txt b/source/index.txt index cd3e5d2a..f2cb82be 100644 --- a/source/index.txt +++ b/source/index.txt @@ -24,6 +24,7 @@ MongoDB PHP Library /data-formats /compatibility /whats-new + /upgrade FAQ /reference diff --git a/source/upgrade.txt b/source/upgrade.txt new file mode 100644 index 00000000..aab0d18d --- /dev/null +++ b/source/upgrade.txt @@ -0,0 +1,99 @@ +.. _php-upgrade: + +======================= +Upgrade Driver Versions +======================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: compatibility, backwards compatibility + +Overview +-------- + +On this page, you can learn how to upgrade your driver to a new version. This +page also includes the changes you must make to your application when you +upgrade to a new version of the {+php-library+}. + +How to Upgrade +-------------- + +Before you upgrade, perform the following actions: + +- Ensure the new {+driver-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 ` + page. +- Address any breaking changes between the driver version + your application is using and your planned upgrade version in the + :ref:`Breaking Changes ` section. + +.. tip:: + + To ensure compatibility across {+mdb-server+} versions when + upgrading driver versions, use the :ref:`{+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 ```` 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- + +To upgrade the PHP library version, replace ```` 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: + +Detailed installation instructions may be found in the +:php:`PHP.net documentation `. + +.. _php-breaking-changes: + +Breaking Changes +---------------- + +A breaking change is a change of a convention or a behavior starting in a specific +version of the driver. This type of change may prevent your application from working +properly if not addressed before upgrading the driver. + +The breaking changes in this section are categorized by the driver version that introduced +them. When upgrading driver 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 `__. + +Version 1.20 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- Drops support for {+mdb-server+} 3.6. + +Version 1.19 and Earlier +~~~~~~~~~~~~~~~~~~~~~~~~ + +For driver versions 1.19 and earlier, see the release notes and associated +JIRA tickets for each release on `GitHub `__.