Upgrade Library Versions

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:

Address any breaking changes between the library version your application is using and your planned upgrade version in the Breaking Changes section.
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 Compatibility Changes section and the MongoDB PHP Library Compatibility page.

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. Only major library versions introduce breaking changes. When upgrading 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.

Compatibility Changes

This section describes the MongoDB Server and PHP compatibility changes introduced in MongoDB PHP Library version releases.

Version 1.x Compatibility Changes

This library version introduces the following compatibility changes:

Drops support for MongoDB Server 3.6 in MongoDB PHP Library v1.20

Tip

Earlier Library Versions

To view compatibility changes for MongoDB PHP Library versions 1.19 and earlier, see the release notes and associated JIRA tickets for each release on GitHub.

Back

What's New

FAQ