Why We Dropped mongodb/mongodb 1.x Support and Committed to ^2.0
Adam C. |

When maintaining an open-source PHP library that integrates with MongoDB, one of the early design questions is:

"Should I support multiple versions of mongodb/mongodb?"
"Can I safely commit a composer.lock if I do?"

Photo by Ben Griffiths on Unsplash

We initially tried to support both version ^1.20 and ^2.0 of mongodb/mongodb, with this in our composer.json:

"require": {
  "mongodb/mongodb": "^1.20 || ^2.0"
}

At first glance, this seems like a flexible, future-proof approach — until you run into Composer's core behavior:

The Hidden Limitation: composer.lock Can Only Lock to One Version

Even if your composer.json allows both:

"mongodb/mongodb": "^1.20 || ^2.0"

When you run composer update, Composer:

Detects the current PHP environment and installed extensions (like ext-mongodb)

Resolves a compatible version

Locks that version into composer.lock

This means your composer.lock will always contain just one version — either 1.x or 2.x.

So what happens if someone installs your library in a different environment?

If they run composer install and their ext-mongodb version doesn’t match the one used to generate the lock file, Composer throws an error.

This defeats the goal of being "compatible with both."

Why This Matters for Open Source Libraries

Open source libraries should be flexible. You want developers to:

composer require your/library

And have Composer resolve the correct version for their environment — whether they’re using ext-mongodb 1.x or 2.x.

But if you commit a composer.lock locked to mongodb/mongodb 2.x, and a user has ext-mongodb 1.x, they'll get:

Your lock file does not contain a compatible set of packages...

Even though your composer.json technically supports their setup.

Our Solution: Drop 1.x, Move Forward

To avoid this ambiguity and keep the setup clean, we decided to:

Drop support for mongodb/mongodb 1.x

Require:

"mongodb/mongodb": "^2.0",
"ext-mongodb": "^2.0"

Commit a consistent composer.lock so all installs are reliable

This simplifies everything:

No compatibility forks

No runtime surprises

Clear expectations for contributors and users

Final Recommendation

If you’re maintaining a library, and truly want to support multiple extension versions:

✅ Use ^1.20 || ^2.0 in composer.json

❌ Do not commit composer.lock

If you're building an app or CLI tool, or you want consistency across environments:

✅ Commit composer.lock

✅ Stick to a single version of mongodb/mongodb and its required extension

TL;DR

composer.lock only locks one version, no matter how flexible your composer.json is.

Committing the lock file while trying to support multiple versions breaks cross-environment compatibility.

We chose clarity and consistency: mongodb/mongodb ^2.0, and a committed lock file that just works.