Docs Menu
Docs Home
/
Languages
/
PHP
/
PHP Library Manual

Upgrade Library Versions

On this page

  • Overview
  • How to Upgrade
  • 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 MongoDB PHP Library. This page also describes how to upgrade your PHP extension to a new version.

How to Upgrade

Before you upgrade, perform the following actions:

  • Ensure the new PHP library version is compatible with the MongoDB Server versions your application connects to and the PHP version your application compiles with. For version compatibility information, see the MongoDB PHP Library Compatibility page.

  • Address any breaking changes between the library version your application is using and your planned upgrade version in the Breaking Changes section.

Tip

To ensure compatibility across MongoDB Server versions when upgrading library versions, use the 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:

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:

composer require mongodb/mongodb:<version-number>

Detailed installation instructions may be found in the PHP.net documentation.

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.

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 CommandSubscriber in your application.

Version 1.20 Breaking Changes

This library version introduces the following breaking changes:

  • Drops support for MongoDB 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.

Back

What's New

Next

FAQ