Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » https://pecl.php.net/package/mongodb
Linux, Unix, and macOS users may run the following command to install the extension:
$ sudo pecl install mongodb
On systems with multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), each version of PHP will have its own pecl command and php.ini file(s). Additionally, each PHP environments (e.g. CLI, web) may use separate php.ini files.
As of extension version 1.17.0, PECL will prompt for various
configure options. To install the extension with default
options in a non-interactive script, empty string input may be piped to
pecl install using the yes command:
$ yes '' | sudo pecl install mongodb
A complete list of supported configure options can be
found in the package.xml file included in the PECL
package. To install the extension with specific configure
options in a non-interactive script, the
--configureoptions option for
pecl install may be used:
$ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb
By default, installing the extension via PECL will use bundled versions of » libbson, » libmongoc, and » libmongocrypt and attempt to automatically configure them.
Note: If the build process fails to find an SSL library, check that the development packages (e.g.
libssl-dev) and » pkg-config are both installed. If that does not resolve the problem, consider using the manual installation process.
Finally, add the following line to the php.ini file for each environment that will need to use the extension:
extension=mongodb.so
» Homebrew 1.5.0 deprecated the » Homebrew/php tap and removed formulae for individual PHP extensions. Going forward, macOS users are advised to install the » php formula and follow the standard PECL installation instructions using the pecl command provided by the Homebrew PHP installation.
Precompiled binaries are attached to the project's » Github releases. Archives are published for various combinations of PHP version, thread safety (TS or NTS), and architecture (x86 or x64). Determining the correct archive for the PHP environment and extract the php_mongodb.dll file to the extension directory ("ext" by default).
Add the following line to the php.ini file for each environment that will need to use the extension:
extension=php_mongodb.dll
Failure to select the correct binary will result in an error when attempting to load the extension DLL at runtime:
PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
Ensure that the downloaded DLL corresponds to the following PHP runtime properties:
PHP_VERSION)PHP_ZTS)PHP_INT_SIZE)In addition to the aforementioned constants, these properties can also be inferred from phpinfo(). If a system has multiple PHP runtimes installed, double-check that the phpinfo() output is for the correct environment.
Note: Additional DLL dependencies for Windows Users
In order for this extension to work, there are DLL files that must be available to the Windows system PATH. For information on how to do this, see the FAQ entitled "How do I add my PHP directory to the PATH on Windows". Although copying DLL files from the PHP folder into the Windows system directory also works (because the system directory is by default in the system's PATH), this is not recommended. This extension requires the following files to be in the PATH: libsasl.dll
For developers and users interested in the latest bugfixes, the extension may be compiled from the latest source code on » Github. Run the following commands to clone and build the project:
$ git clone https://github.com/mongodb/mongo-php-driver.git $ cd mongo-php-driver $ git submodule update --init $ phpize $ ./configure $ make all $ sudo make install
On systems with multiple version of PHP installed (e.g. macOS default, Homebrew, » XAMPP), each version of PHP will have its own phpize command and php.ini file(s). Additionally, each PHP environments (e.g. CLI, web) may use separate php.ini files.
By default, the extension will use bundled versions of
» libbson,
» libmongoc, and
» libmongocrypt and
attempt to configure them automatically. If these libraries are already
installed as system libraries, the extension can utilize them by
specifying --with-mongodb-system-libs=yes as an option to
configure.
For a complete list of configure options, run
configure --help.
When using bundled versions of libmongoc and libmongocrypt, the extension
will also attempt to select an SSL library according to the
--with-mongodb-ssl configure option.
As of extension version 1.17.0, OpenSSL is always preferred by default.
Previously, Secure Transport was the default on macOS and OpenSSL was the
default on all other platforms.
Note:
If the build process fails to find an SSL library, check that the development packages (e.g.
libssl-dev) and » pkg-config are both installed.When using Homebrew on macOS, it is common for a system to have multiple versions of OpenSSL installed. To ensure that the desired version of OpenSSL is selected, the
PKG_CONFIG_PATHenvironment variable may be used to control the search path forpkg-config.
The final build step, make install, will report where mongodb.so has been installed, similar to:
Installing shared extensions: /usr/lib/php/extensions/debug-non-zts-20220829/
Ensure that the extension_dir option in php.ini points to the directory where mongodb.so was installed. The option may be queried by running:
$ php -i | grep extension_dir
extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
/usr/lib/php/extensions/debug-non-zts-20220829
If the directories differ, either change extension_dir in php.ini or manually move mongodb.so to the correct directory.
Finally, add the following line to the php.ini file for each environment that will need to use the extension:
extension=mongodb.so