Installing the MongoDB PHP Extension with PECL

Informazioni per l'installazione di questa estensione PECL possono essere trovate nel capitolo del manuale intitolato Installazione delle estensioni PECL. Informazioni aggiuntive come nuove release, download, file sorgenti, informazioni del manutentore e un CHANGELOG possono essere trovate qui: » 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.

Nota: 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

Installing the MongoDB PHP Extension on macOS with Homebrew

» 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.

Installing the MongoDB PHP Extension on Windows

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_VERSION)
• Thread safety (PHP_ZTS)
• Architecture (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.

Nota: Additional DLL dependencies for Windows Users

Perché questa estensione possa funzionare, delle DLL devono essere disponibili nel PATH di sistema di Windows. Vedere la FAQ intitolata "Come aggiungere la cartella di PHP al PATH in Windows" per informazioni su come farlo. Anche se copiare i file DLL dalla cartella di PHP alla cartella di sistema di Windows funziona (poiché la cartella di sistema è di default nel PATH di sistema), non è raccomandato. Questa estensione richiede che i seguenti file siano nel PATH: libsasl.dll

Building the MongoDB PHP Driver from source

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.

Nota:

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_PATH environment variable may be used to control the search path for pkg-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