mongo-php-driver: the low level PHP extension under the MongoDB PHP library

An extension with a deliberately minimal API

The MongoDB PHP Driver is the official MongoDB driver for PHP, hosted at php.net/mongodb. It is described as an extension developed atop the libmongoc and libbson libraries, and it provides a minimal API for core driver functionality: commands, queries, writes, connection management, and BSON serialization.

The word minimal is the important one. This is not the library most PHP developers interact with. Higher level capabilities such as query builders, individual command helper methods and GridFS come from userland PHP libraries, and the README is explicit that application developers should use the extension in conjunction with the MongoDB PHP library, which implements the same higher level APIs found in MongoDB drivers for other languages.

So there are two layers. The extension is the C code that owns the socket, the wire protocol and the BSON encoding and decoding. The library is the Composer package mongodb/mongodb, a PHP layer on top of that. The distinction matters for issue reporting too: extension issues go to the PHPC project in MongoDB's JIRA, while library issues go to PHPLIB, and general support questions go to MongoDB's technical support channels.

Security vulnerabilities in a driver or any other MongoDB project are reported separately, following MongoDB's own vulnerability reporting instructions rather than the public issue tracker.

The source tree reflects the two language split. There is phongo.c and phongo.h with a phongo_version.h header, src/ for the extension code, tests/, scripts/, bin/, a config.m4 for the Unix build and a config.w32 for Windows, a Makefile.frag, a composer.json, a template.rc, and the Vagrantfile and .evergreen/ directory used for continuous integration environments.

Installing with pie, and constraining the version you get

The recommended installation path is pie, described as a modern tool for managing PHP extensions. With pie on the system, the extension installs in one command.

pie install mongodb/mongodb-extension

That downloads, builds and enables the extension for your PHP installation, so there is no separate build step and no manual editing of an ini file.

Versions can be constrained by appending a constraint after the package name.

pie install mongodb/mongodb-extension:^2.1.0

The README explains exactly what that constraint means: it installs the latest version greater than or equal to 2.1.0 and less than 3.0.0-dev. Pinning this way is the mechanism to hold a deployment on a known release line rather than tracking whatever the newest build is.

This is a meaningful change in practice because the repository now carries several release lines at once. The recent releases show 2.5.5, 2.1.12 and 1.21.12 all published on 2026-10-15, and the default branch is v2.x. Three branches, three version series, one release day.

The repository also carries an UPGRADE-2.0.md file, which is the document to read before moving across the 2.0 boundary, and a RELEASING.md that describes how releases are cut.

The PECL path is deprecated and skips signature verification

The older install method still works but is marked deprecated, with a note that using pecl to install extensions is deprecated. The build and install steps are:

pecl install mongodb
echo "extension=mongodb.so" >> `php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||"`

The second line appends the extension directive to the php.ini that php --ini reports as loaded, which is the usual way to enable a compiled extension without editing the file by hand.

The deprecation is about the tool rather than the extension, and the driver follows semantic versioning for its releases.

The more consequential difference is integrity. The README states plainly that no verification is done when using pecl to install the package, and that integrity validation is not yet supported when installing with pie either. If you require signature verification, the instructions point you at the manual or PECL installation methods, with the caveat about downloading the tarball yourself.

That is the trap in this section. The advice to use PECL for verification does not mean a plain pecl install gives you verification. To actually verify a PECL package you download the tarball from the GitHub release, check the signature, and then install from that local file:

pecl install mongodb-X.Y.Z.tgz

Windows has its own wrinkle. Binaries are distributed through GitHub releases as a ZIP package, and the release also contains a detached signature file for the PECL package, named php_mongodb-X.Y.Z.zip.sig alongside the archive. Windows binaries distributed directly through PECL are not signed by MongoDB and cannot be verified, so the GitHub release is the only path that can be checked.

Signed releases: the PHP team GPG key is what to trust

Releases are created automatically and signed using the PHP team's GPG key, and the signing applies to the git tag as well as to the release packages in a GitHub release. Verification starts by importing the key.

gpg --import php-driver.asc

With the key in the keyring, a PECL package is checked by verifying its detached signature against the tarball:

gpg --verify mongodb-X.Y.Z.tgz.sig mongodb-X.Y.Z.tgz

And the Windows ZIP is checked the same way:

gpg --verify php_mongodb-X.Y.Z.zip.sig php_mongodb-X.Y.Z.zip

The arrangement is worth understanding rather than just copying. MongoDB signs with the PHP team's key rather than a MongoDB key, which means the trust anchor is the PHP project, and the signature covers the tag as well as the artefacts. PECL packages are also published on the PECL homepage at pecl.php.net/mongodb, so the package you receive depends on which source you used, and only the GitHub release artefacts carry the detached signature files.

For a production deployment where the supply chain matters, the sequence is: fetch from the GitHub release, import the key, verify the detached signature, then install from the verified local file. The repository also ships an sbom.json file, alongside a THIRD_PARTY_NOTICES file and a CREDITS file.

The stated limitation is the honest part of this story. Neither pie nor a plain pecl install performs this validation for you, so the security property only exists if you build the verification into your own pipeline.

Where the extension stops and the library begins

The clearest way to think about this project is as the layer below your application code, and the boundary explains several practical things.

If you want a query builder, GridFS, or helper methods for individual commands, none of that is here. The README says those come from userland libraries, and names the MongoDB PHP library as the one to pair with, distributed on Packagist as mongodb/mongodb for Composer. Installing only the extension gives you the low level API and nothing else.

The upside of the split is that the extension is small in surface area. Commands, queries, writes, connection management and BSON serialization is a short list, and it is the layer that has to track the server's wire protocol, so keeping it thin keeps the surface that needs native code review small. It is also built on libmongoc and libbson, the C libraries that the other MongoDB drivers also use, which is what keeps protocol behaviour consistent across languages.

The downside is that you now have two things to install and two things to version. A Composer lock file tells you the library version, but nothing in it tells you the extension version, and the two have their own compatibility expectations. If you pin the extension with a pie constraint such as ^2.1.0, that pin lives outside Composer's dependency resolution, in your build tooling, and the two can drift apart silently.

The alternative to a native extension is not really an alternative, it is a different shape. A pure PHP driver would avoid the build step and the version pinning entirely, at the cost of not reusing libmongoc. The official driver chose the native path, and the version branching, the PECL deprecation and the pie adoption are all consequences of that choice.

Licence, contribution flow and what the CI runs

The licence field on the repository says Apache-2.0, which is the same permissive licence MongoDB uses across its open source projects. This is not legal advice, but for an extension that gets compiled into your PHP runtime it is a straightforward arrangement with the attribution and patent grant you would expect.

Development is tracked in the PHPC project in MongoDB's JIRA, and CONTRIBUTING.md carries the documentation for contributing. That JIRA-first workflow is worth noting if you plan to contribute, because it differs from a GitHub issue-first project and the two trackers serve different purposes: PHPC for the extension, PHPLIB for the library.

The repository's tooling shows a native C project with modern static analysis. There is a .clang-format file at the root with a matching CI workflow for coding standards, a .llvm-cov.sh script and a coveralls badge for coverage, a .semgrepignore file, a .evergreen/ directory for the Evergreen CI system, a Vagrantfile for local environments, and .claude/ for Claude Code configuration. The .gitmodules file points at the libmongoc and libbson dependencies as submodules, which explains why a build needs those sources present.

The CREDITS and THIRD_PARTY_NOTICES files, plus sbom.json, mean the licensing and provenance of the bundled C libraries are documented rather than implied. For a driver that links a large C codebase into your web server's process, that documentation is the thing to check before you accept the dependency, alongside the signed releases.

The last push was on 2026-10-19, one release day after the 2.5.5, 2.1.12 and 1.21.12 tags on 2026-10-15, so the tree is being worked on while three lines are shipped in parallel.

Editorial conclusion

mongo-php-driver is the right dependency when your PHP application talks to MongoDB, because it is the official extension and the one the MongoDB PHP library expects. It is the wrong choice if you are looking for a query builder or GridFS, since those live in the separate mongodb/mongodb library, and it is the wrong choice if you need a single verification method across every installation path, because PECL installs perform no signature check. Before adopting it, pick the install method deliberately: use pie for convenience, use the manual or PECL route when you need GPG signature verification, and note that the newest tags land on several branches at once, with 2.5.5, 2.1.12 and 1.21.12 all published on 2026-10-15.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mongodb/mongo-php-driver on GitHub
3. Project website
4. README
5. Releases