From 585da96f2b6d54316b029f746cba71b37e7bb2d6 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 17:44:41 -0400 Subject: [PATCH 01/12] DOCSP-41992 Upgrade versions --- snooty.toml | 5 ++- source/upgrade.txt | 109 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 112 insertions(+), 2 deletions(-) create mode 100644 source/upgrade.txt diff --git a/snooty.toml b/snooty.toml index 051763b9..940aaa67 100644 --- a/snooty.toml +++ b/snooty.toml @@ -25,8 +25,9 @@ toc_landing_pages = [ "/databases-collections", "/write", "/indexes", - "/security" - "/data-formats" + "/security", + "/data-formats", + "/upgrade" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" diff --git a/source/upgrade.txt b/source/upgrade.txt new file mode 100644 index 00000000..11628e3c --- /dev/null +++ b/source/upgrade.txt @@ -0,0 +1,109 @@ +.. 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 +-------- + +This page describes the changes you must make to your application +when you upgrade to a new version of the {+driver-short+}. + +This page describes the changes you must make to your application +when you upgrade to a new version of the {+driver-short+}. + +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:`{+driver-short+} 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+} `. + +.. _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. + +- Deprecate iterators for database, collection, and index enumeration. + +Version 1.18 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- Deprecate setting ``disableMD5`` to ``false`` when instantiating a Bucket due to + deprecated MD5 encoding. The default value for the setting is now ``true``. + +Version 1.17 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This driver version introduces the following breaking changes: + +- Upgrades the ``mongodb`` extension requirement to 1.17.0. + +- Requires PHP 7.4 or newer. + +- Removes support for PHP 7.2 and 7.3. + +- Remove aggregate compatibility logic for {+mdb-server+} versions less than + 3.6, including removing the ``useCursor`` option. + +Version 1.16 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Upgrades the ``mongodb`` extension requirement to 1.16.0. + +- Deprecate ``IndexInfo::isGeoHaystack()``. ``geoHaystack`` was removed in + {+mdb-server+} 5.0 and later. + +- Drop support for Composer 1.x. + +- Remove ``$server`` argument in ``Explainable::getCommandDocument``. + +- Remove ``getNonce`` command usage for {+mdb-server+} 6.2 and later. + +Version 1.15 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Upgrades the ``mongodb`` extension requirement to 1.15.0. From 15e475f0da0d0fea1e72a68b551b833cc81ae654 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 17:52:14 -0400 Subject: [PATCH 02/12] toc --- source/index.txt | 1 + source/upgrade.txt | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/source/index.txt b/source/index.txt index 7ffdd83a..0d1e9441 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,6 +22,7 @@ MongoDB PHP Library /data-formats /compatibility /whats-new + /upgrade FAQ /reference diff --git a/source/upgrade.txt b/source/upgrade.txt index 11628e3c..231e3cd0 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -92,6 +92,8 @@ This driver version introduces the following breaking changes: Version 1.16 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This driver version introduces the following breaking changes: + - Upgrades the ``mongodb`` extension requirement to 1.16.0. - Deprecate ``IndexInfo::isGeoHaystack()``. ``geoHaystack`` was removed in @@ -106,4 +108,6 @@ Version 1.16 Breaking Changes Version 1.15 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +This driver version introduces the following breaking changes: + - Upgrades the ``mongodb`` extension requirement to 1.15.0. From 9670327ee8ad148ab7258134d2500dab13192fa8 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 18:03:53 -0400 Subject: [PATCH 03/12] edits --- source/upgrade.txt | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 231e3cd0..7e7d8df2 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -23,15 +23,12 @@ Overview This page describes the changes you must make to your application when you upgrade to a new version of the {+driver-short+}. -This page describes the changes you must make to your application -when you upgrade to a new version of the {+driver-short+}. - 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:`{+driver-short+} Compatibility ` + :ref:`{+php-library+} Compatibility ` page. - Address any breaking changes between the driver version your application is using and your planned upgrade version in the @@ -84,10 +81,8 @@ This driver version introduces the following breaking changes: - Requires PHP 7.4 or newer. -- Removes support for PHP 7.2 and 7.3. - -- Remove aggregate compatibility logic for {+mdb-server+} versions less than - 3.6, including removing the ``useCursor`` option. +- Remove aggregate compatibility logic, like the ``useCursor`` option, for + {+mdb-server+} versions less than 3.6. Version 1.16 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 84825148b60c6b1cb6a5258cbbd369d3c8ea7fa8 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 18:15:00 -0400 Subject: [PATCH 04/12] how to upgrade sections --- source/upgrade.txt | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 7e7d8df2..a1e9945f 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -20,8 +20,12 @@ Upgrade Driver Versions Overview -------- -This page describes the changes you must make to your application -when you upgrade to a new version of the {+driver-short+}. +This page describes how to upgrade your driver to a new version and the changes +you must make to your application when you upgrade to a new version of the +{+driver-short+}. + +How to Upgrade +-------------- Before you upgrade, perform the following actions: @@ -39,6 +43,17 @@ Before you upgrade, perform the following actions: To ensure compatibility across {+mdb-server+} versions when upgrading driver versions, use the :ref:`{+stable-api+} `. +To upgrade your driver version, replace "version number" with the version number +you would like to upgrade to and run the following command in your application's +directory: + +.. code-block:: bash + + composer require mongodb/mongodb: + +Installation instructions for the ``mongodb`` extension may be found in the +`PHP.net documentation `__. + .. _php-breaking-changes: Breaking Changes From dfe83b7b060915bf3ce6d63ad74a2c6f58888706 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 18:19:04 -0400 Subject: [PATCH 05/12] style --- source/upgrade.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index a1e9945f..a36e4003 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -44,7 +44,7 @@ Before you upgrade, perform the following actions: upgrading driver versions, use the :ref:`{+stable-api+} `. To upgrade your driver version, replace "version number" with the version number -you would like to upgrade to and run the following command in your application's +you want to upgrade to and run the following command in your application's directory: .. code-block:: bash From 6e3538dadb11b4d16a304192a59e67348443f62d Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 18:21:21 -0400 Subject: [PATCH 06/12] edit --- source/upgrade.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index a36e4003..7bec815c 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -20,9 +20,9 @@ Upgrade Driver Versions Overview -------- -This page describes how to upgrade your driver to a new version and the changes -you must make to your application when you upgrade to a new version of the -{+driver-short+}. +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 {+driver-short+}. How to Upgrade -------------- From 6610b561f2f13ca6ea06f044be9ee542bb07e779 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 25 Sep 2024 18:24:27 -0400 Subject: [PATCH 07/12] edit --- source/upgrade.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 7bec815c..068841f4 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -22,7 +22,7 @@ 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 {+driver-short+}. +upgrade to a new version of the {+php-library+}. How to Upgrade -------------- From 89883229617e2d6b15672e3bda3cba34b22c2817 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 26 Sep 2024 10:15:59 -0400 Subject: [PATCH 08/12] review comments --- source/upgrade.txt | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 068841f4..c76df8fd 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -43,16 +43,16 @@ Before you upgrade, perform the following actions: To ensure compatibility across {+mdb-server+} versions when upgrading driver versions, use the :ref:`{+stable-api+} `. -To upgrade your driver version, replace "version number" with the version number +To upgrade your driver 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: + composer require mongodb/mongodb: Installation instructions for the ``mongodb`` extension may be found in the -`PHP.net documentation `__. +:php:`PHP.net documentation `. .. _php-breaking-changes: @@ -77,14 +77,14 @@ This driver version introduces the following breaking changes: - Drops support for {+mdb-server+} 3.6. -- Deprecate iterators for database, collection, and index enumeration. +- Deprecates iterators for database, collection, and index enumeration. Version 1.18 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This driver version introduces the following breaking changes: -- Deprecate setting ``disableMD5`` to ``false`` when instantiating a Bucket due to +- Deprecates setting ``disableMD5`` to ``false`` when instantiating a Bucket due to deprecated MD5 encoding. The default value for the setting is now ``true``. Version 1.17 Breaking Changes @@ -96,7 +96,7 @@ This driver version introduces the following breaking changes: - Requires PHP 7.4 or newer. -- Remove aggregate compatibility logic, like the ``useCursor`` option, for +- Removes aggregate compatibility logic, like the ``useCursor`` option, for {+mdb-server+} versions less than 3.6. Version 1.16 Breaking Changes @@ -106,14 +106,14 @@ This driver version introduces the following breaking changes: - Upgrades the ``mongodb`` extension requirement to 1.16.0. -- Deprecate ``IndexInfo::isGeoHaystack()``. ``geoHaystack`` was removed in +- Deprecates ``IndexInfo::isGeoHaystack()``. ``geoHaystack`` was removed in {+mdb-server+} 5.0 and later. -- Drop support for Composer 1.x. +- Drops support for Composer 1.x. -- Remove ``$server`` argument in ``Explainable::getCommandDocument``. +- Removes ``$server`` argument in ``Explainable::getCommandDocument``. -- Remove ``getNonce`` command usage for {+mdb-server+} 6.2 and later. +- Removes ``getNonce`` command usage for {+mdb-server+} 6.2 and later. Version 1.15 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From ce8408f78a4b4cb23dfcd99693973aaef8872f59 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 26 Sep 2024 10:16:22 -0400 Subject: [PATCH 09/12] ref --- source/upgrade.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index c76df8fd..dbd3a41b 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -1,4 +1,4 @@ -.. php-upgrade: +.. _php-upgrade: ======================= Upgrade Driver Versions From 9a7aa0849d5dc671dae64e92de1d3b876235824c Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 26 Sep 2024 15:15:40 -0400 Subject: [PATCH 10/12] add ext upgrade command --- source/upgrade.txt | 64 ++++++++++++++-------------------------------- 1 file changed, 19 insertions(+), 45 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index dbd3a41b..1121eb18 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -43,15 +43,28 @@ Before you upgrade, perform the following actions: To ensure compatibility across {+mdb-server+} versions when upgrading driver versions, use the :ref:`{+stable-api+} `. -To upgrade your driver version, replace ```` with the version number +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, use the following command: + .. code-block:: bash composer require mongodb/mongodb: -Installation instructions for the ``mongodb`` extension may be found in the +Detailed installation instructions may be found in the :php:`PHP.net documentation `. .. _php-breaking-changes: @@ -77,47 +90,8 @@ This driver version introduces the following breaking changes: - Drops support for {+mdb-server+} 3.6. -- Deprecates iterators for database, collection, and index enumeration. - -Version 1.18 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This driver version introduces the following breaking changes: - -- Deprecates setting ``disableMD5`` to ``false`` when instantiating a Bucket due to - deprecated MD5 encoding. The default value for the setting is now ``true``. - -Version 1.17 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This driver version introduces the following breaking changes: - -- Upgrades the ``mongodb`` extension requirement to 1.17.0. - -- Requires PHP 7.4 or newer. - -- Removes aggregate compatibility logic, like the ``useCursor`` option, for - {+mdb-server+} versions less than 3.6. - -Version 1.16 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This driver version introduces the following breaking changes: - -- Upgrades the ``mongodb`` extension requirement to 1.16.0. - -- Deprecates ``IndexInfo::isGeoHaystack()``. ``geoHaystack`` was removed in - {+mdb-server+} 5.0 and later. - -- Drops support for Composer 1.x. - -- Removes ``$server`` argument in ``Explainable::getCommandDocument``. - -- Removes ``getNonce`` command usage for {+mdb-server+} 6.2 and later. - -Version 1.15 Breaking Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This driver version introduces the following breaking changes: +Version 1.19 and Earlier +~~~~~~~~~~~~~~~~~~~~~~~~ -- Upgrades the ``mongodb`` extension requirement to 1.15.0. +For driver versions 1.19 and earlier, see the release notes and associated +JIRA tickets for each release on `GitHub `__. From 807fc78fcf7f74843445d753ec592f2b9dd3b1a7 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 26 Sep 2024 15:20:59 -0400 Subject: [PATCH 11/12] edit --- source/upgrade.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 1121eb18..4133eb29 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -58,7 +58,7 @@ directory: pecl upgrade mongodb- -To upgrade the PHP Library version, use the following command: +To upgrade the PHP library version, run the following command: .. code-block:: bash From f03e46ce06860c4a1b87f8affc6e5b794ad92616 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 27 Sep 2024 11:50:17 -0400 Subject: [PATCH 12/12] edit copy --- source/upgrade.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 4133eb29..aab0d18d 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -58,7 +58,9 @@ directory: pecl upgrade mongodb- -To upgrade the PHP library version, run the following command: +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