MongoDB PHP Library

MongoDB PHP Library (published on Packagist as mongodb/mongodb) is the official high-level abstraction MongoDB maintains on top of its lower-level PHP driver extension (ext-mongodb). Where the extension exposes a minimal API for issuing raw commands, queries, and write operations, this library layers on Client, Database, and Collection objects with a full-featured API matching MongoDB’s other language drivers, plus first-class support for aggregation pipelines, GridFS file storage, and change streams.

It is the library MongoDB itself points developers to in its PHP documentation and is the dependency almost every PHP application talking to MongoDB installs via Composer, making it the de facto standard rather than one option among several.

What You Get

• Client, Database, and Collection classes mirroring the API shape of MongoDB’s other official drivers (Node.js, Python, Java)
• A typed query and aggregation pipeline builder (MongoDB\Builder namespace) for constructing stages, expressions, and search queries without hand-writing arrays
• Full CRUD operation classes (InsertOne/InsertMany, UpdateOne/UpdateMany, DeleteOne/DeleteMany, FindOneAndUpdate, bulk writes) as discrete, testable Operation objects
• GridFS Bucket, ReadableStream, and WritableStream classes for storing and retrieving files larger than the 16MB BSON document limit
• ChangeStream support for watching real-time collection, database, or cluster-level changes
• Codec/Encoder/Decoder interfaces (MongoDB\Codec) for mapping PHP objects to and from BSON documents, including a Persistable interface for custom serialization

Common Use Cases

• Connecting a PHP web application (Laravel, Symfony, or plain PHP) to a MongoDB replica set or Atlas cluster for CRUD-driven features
• Building aggregation pipelines with the typed Builder API for reporting, analytics, or search-index queries (including Atlas Search)
• Streaming large binary files (images, videos, backups) into and out of MongoDB via GridFS instead of the 16MB document limit
• Reacting to real-time data changes with change streams for event-driven or cache-invalidation workflows
• Implementing multi-document ACID transactions across collections with client-managed sessions

Under The Hood

Architecture The library is a thin, well-factored abstraction layer over the compiled mongodb PECL extension (ext-mongodb), not a from-scratch wire-protocol implementation. Client (src/Client.php) wraps a MongoDB\Driver\Manager and exposes selectDatabase()/selectCollection(), which construct Database and Collection objects that in turn delegate every operation (find, insert, aggregate, drop, etc.) to a dedicated Operation class under src/Operation/ (45 files, one per command). This command pattern keeps each operation’s option-parsing and validation isolated and independently testable rather than bloating Collection with inline logic. Cross-cutting concerns — BSON encoding/decoding (src/Codec/), query/aggregation pipeline construction (src/Builder/, covering Accumulator, Expression, Pipeline, Query, Search, Stage, Update sub-namespaces), and GridFS file streaming (src/GridFS/, with Bucket, ReadableStream, WritableStream) — are each factored into their own top-level namespace rather than mixed into the core classes.

Tech Stack Pure PHP 8.1+ ("php": "^8.1" in composer.json), with a hard runtime dependency on ext-mongodb ^2.3 (the C-extension driver this library sits on top of) plus psr/log for logging and a symfony/polyfill-php85 polyfill. It declares zero other userland runtime dependencies, keeping the install footprint small. Dev tooling is comprehensive: PHPUnit 10 for tests, Psalm (with a checked-in psalm-baseline.xml) and Rector for static analysis and automated upgrades, and doctrine/coding-standard plus PHP_CodeSniffer for style enforcement, all wired into a single composer checks script.

Code Quality The test suite is substantial — 521 PHP files under tests/, spanning unit, functional (spec-runner-driven), and GridFS-specific suites, reflecting the library’s role as MongoDB’s officially supported driver where correctness against the MongoDB wire spec is non-negotiable. Every public class carries structured PHPDoc blocks (@param, @throws, @see links to both PHP.net and MongoDB manual pages), and the codebase leans on typed properties and strict return types throughout (e.g. Client::__construct types every parameter and documents every thrown exception class). Custom exception hierarchies live under src/Exception/, giving callers granular catch targets (InvalidArgumentException, UnexpectedValueException, UnsupportedException) distinct from the underlying driver’s own exception types.

API Design The public surface closely mirrors MongoDB’s Node.js/Python/Java drivers, so developers moving between languages find the same find/insertOne/aggregate vocabulary. Getting started requires only composer require mongodb/mongodb plus the compiled mongodb PECL extension, and a new Client() call with no arguments connects to a local default instance. The typed pipeline Builder (MongoDB\Builder\Pipeline, Stage, Expression) is a notable DX investment over hand-rolled nested arrays, catching malformed aggregation stages at the type level rather than at query-execution time on the server.