Class 'MongoDB\Client' not found, mongodb extension installed

Class 'MongoDB\Client' not found, mongodb extension installed

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

The MongoDB\Client Class Error: A PHP Version Mismatch

Seeing a fatal error like Class 'MongoDB\Client' not found is a classic sign of a version mismatch rather than a missing extension. You have confirmed that the extension is loaded by checking extension_loaded("mongodb"), which returns true, yet your application fails to instantiate the client. This discrepancy almost always points to a conflict between the PHP version running your web server and the specific version of the MongoDB PHP driver installed via PECL or Composer.

The MongoDB PHP library was reworked significantly in recent years, most notably when it transitioned from the legacy C-extension (php_mongodb) to the new C-extension based on the BSON library. If you are using an older installation method where you manually copied php_mongodb.dll into your ext folder, that file likely corresponds to a specific PHP major version (e.g., PHP 5.x or early PHP 7/8).

If your application is running on PHP 8.1 or later, the legacy DLL will not contain the MongoDB\Client class in its modern form. Instead, it might define classes under different namespaces or simply fail to expose the expected symbols to the runtime. The phpinfo() output you referenced likely shows Active Modules: mongodb, but it does not guarantee that the specific version of the driver matches the active PHP interpreter.

The modern solution involves using the Composer package mongodb/mongodb rather than the legacy PECL extension. This package is maintained separately and ensures compatibility with current PHP versions. You should stop manually copying DLL files and instead rely on dependency management tools like Composer.

To resolve this, first remove the legacy file to prevent any ambiguity about which library is being loaded. Delete php_mongodb.dll from your ext directory if it exists there. Then, ensure your php.ini does not reference a version-specific extension string that might conflict with the new package.

Next, use Composer to install the correct driver:

composer require mongodb/mongodb

This command installs a PHAR or source-based extension compatible with your current PHP version (8.x). After installation, verify the class is available by running a simple test script that uses require and autoload:

<?php
require 'vendor/autoload.php';

use MongoDB\Client;

$client = new Client();
print_r($client);

If this code runs without errors, the mismatch is resolved. The key takeaway is that manual installation of extensions is error-prone when dealing with versioned libraries like MongoDB. Always prefer Composer-managed dependencies to ensure the binary extension matches your PHP runtime.

Another potential pitfall involves the php.ini configuration file itself. If you have both a legacy extension and a new package installed, there might be duplicate entries or conflicting paths. Ensure that extension=mongodb is present in your active configuration but that no other MongoDB-related extensions are listed. In some environments, particularly shared hosting or older PHP versions, the driver might require explicit compilation flags or specific system libraries like libbson to be installed at the OS level.

If you are building a Laravel application, this issue is even more critical because Laravel relies heavily on modern PHP syntax and often requires specific PHP version constraints defined in its composer.json. If your project demands PHP 8.x but your server is running an older interpreter with an old driver, you will hit these fatal errors immediately upon bootstrapping.

For production environments, always check the exact version of the extension using php -m and cross-reference it with the version expected by your installed packages. If you need to migrate from a legacy setup, plan for a PHP version upgrade alongside the library migration to avoid compatibility issues down the line.

Our network