configure.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<section xml:id="mongodb.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 &reftitle.install;

 <section xml:id="mongodb.installation.pecl">
  <title>Installing the MongoDB PHP Extension with PECL</title>

  <para>
   &pecl.info;
   <link xlink:href="&url.pecl.package;mongodb">&url.pecl.package;mongodb</link>
  </para>

  <para>
   Linux, Unix, and macOS users may run the following command to install the
   extension:
   <programlisting role="shell">
<![CDATA[
$ sudo pecl install mongodb
]]>
   </programlisting>
  </para>

  <para>
   On systems with multiple version of PHP installed (e.g. macOS default,
   Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), each version of PHP
   will have its own <link linkend="install.pecl">pecl</link>
   command and &php.ini; file(s). Additionally, each PHP environments (e.g.
   CLI, web) may use separate &php.ini; files.
  </para>

  <para>
   As of extension version 1.17.0, PECL will prompt for various
   <literal>configure</literal> options. To install the extension with default
   options in a non-interactive script, empty string input may be piped to
   <literal>pecl install</literal> using the <literal>yes</literal> command:
   <programlisting role="shell">
<![CDATA[
$ yes '' | sudo pecl install mongodb
]]>
   </programlisting>
  </para>

  <para>
   A complete list of supported <literal>configure</literal> options can be
   found in the <literal>package.xml</literal> file included in the PECL
   package. To install the extension with specific <literal>configure</literal>
   options in a non-interactive script, the
   <literal>--configureoptions</literal> option for
   <literal>pecl install</literal> may be used:
   <programlisting role="shell">
<![CDATA[
$ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb
]]>
   </programlisting>
  </para>

  <para>
   By default, installing the extension via PECL will use bundled versions of
   <link xlink:href="&url.mongodb.libbson;">libbson</link>,
   <link xlink:href="&url.mongodb.libmongoc;">libmongoc</link>, and
   <link xlink:href="&url.mongodb.libmongocrypt;">libmongocrypt</link> and attempt to
   automatically configure them.
  </para>

  <note>
   <simpara>
    If the build process fails to find an SSL library, check that the
    development packages (e.g. <literal>libssl-dev</literal>) and
    <link xlink:href="&url.mongodb.wiki.pkg-config;">pkg-config</link> are both
    installed. If that does not resolve the problem, consider using the
    <link linkend="mongodb.installation.manual">manual installation</link>
    process.
   </simpara>
  </note>

  <para>
   Finally, add the following line to the &php.ini; file for each environment
   that will need to use the extension:
   <programlisting role="ini">
<![CDATA[
extension=mongodb.so
]]>
   </programlisting>
  </para>
 </section>

 <section xml:id="mongodb.installation.homebrew">
  <title>Installing the MongoDB PHP Extension on macOS with Homebrew</title>

  <para>
   <link xlink:href="&url.brew.1.5.0;">Homebrew 1.5.0</link>
   deprecated the <link xlink:href="&url.mac.homebrew;">Homebrew/php tap</link>
   and removed formulae for individual PHP extensions. Going forward, macOS
   users are advised to install the
   <link xlink:href="&url.brew.php;">php</link> formula
   and follow the standard
   <link linkend="mongodb.installation.pecl">PECL installation instructions</link>
   using the <link linkend="install.pecl">pecl</link> command provided by the
   Homebrew PHP installation.
  </para>
  <para>
   Alternatively, the
   <link xlink:href="https://github.com/shivammathur/homebrew-extensions">shivammathur/extensions tap</link>
   provides formulae for individual PHP extensions. For example, to install the
   extension for PHP 8.4, run:
   <programlisting role="shell">
<![CDATA[
$ brew install shivammathur/extensions/mongodb@8.4
]]>
   </programlisting>
   Please note that only the latest extension version is available in brew.
  </para>
  <note>
   <title>Install required dependencies</title>
   <para>
    To ensure that SSL support can be configured correctly, make sure that the
    <literal>openssl</literal> and <literal>pkgconf</literal> formulae are
    installed. If either of these packages are missing, the extension will be
    compiled with Secure Transport, which can lead to compatibility issues.
   </para>
  </note>
 </section>

 <section xml:id="mongodb.installation.windows">
  <title>Installing the MongoDB PHP Extension on Windows</title>

  <para>
   Precompiled binaries are attached to the project's
   <link xlink:href="&url.mongodb.github.new;/releases/">Github releases</link>.
   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 <filename>php_mongodb.dll</filename>
   file to the extension directory ("ext" by default).
  </para>

  <para>
   Add the following line to the &php.ini; file for each environment that will
   need to use the extension:
   <programlisting role="ini">
<![CDATA[
extension=php_mongodb.dll
]]>
   </programlisting>
  </para>

  <para>
   Failure to select the correct binary will result in an error when attempting
   to load the extension DLL at runtime:
   <programlisting role="txt">
<![CDATA[
PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'
]]>
   </programlisting>
  </para>

  <para>
   Ensure that the downloaded DLL corresponds to the following PHP runtime
   properties:
   <simplelist>
    <member>PHP version (<constant>PHP_VERSION</constant>)</member>
    <member>Thread safety (<constant>PHP_ZTS</constant>)</member>
    <member>Architecture (<constant>PHP_INT_SIZE</constant>)</member>
   </simplelist>
  </para>

  <para>
   In addition to the aforementioned constants, these properties can also be
   inferred from <function>phpinfo</function>. If a system has multiple PHP
   runtimes installed, double-check that the <function>phpinfo</function> output
   is for the correct environment.
  </para>

  <note>
   <title>Additional DLL dependencies for Windows Users</title>
   <para>
    &ext.windows.path.dll;
    <filename>libsasl.dll</filename>
   </para>
  </note>
 </section>

 <section xml:id="mongodb.installation.manual">
  <title>Building the MongoDB PHP Driver from source</title>

  <para>
   For developers and users interested in the latest bugfixes, the extension
   may be compiled from the latest source code on
   <link xlink:href="&url.mongodb.github.new;">Github</link>. Run the following
   commands to clone and build the project:
   <programlisting role="shell">
<![CDATA[
$ 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
]]>
   </programlisting>
  </para>

  <para>
   On systems with multiple version of PHP installed (e.g. macOS default,
   Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), each version of PHP
   will have its own <link linkend="install.pecl.phpize">phpize</link>
   command and &php.ini; file(s). Additionally, each PHP environments (e.g.
   CLI, web) may use separate &php.ini; files.
  </para>

  <para>
   By default, the extension will use bundled versions of
   <link xlink:href="&url.mongodb.libbson;">libbson</link>,
   <link xlink:href="&url.mongodb.libmongoc;">libmongoc</link>, and
   <link xlink:href="&url.mongodb.libmongocrypt;">libmongocrypt</link> and
   attempt to configure them automatically. If these libraries are already
   installed as system libraries, the extension can utilize them by
   specifying <literal>--with-mongodb-system-libs=yes</literal> as an option to
   <literal>configure</literal>.
  </para>

  <para>
   For a complete list of <literal>configure</literal> options, run
   <command>configure --help</command>.
  </para>

  <para>
   When using bundled versions of libmongoc and libmongocrypt, the extension
   will also attempt to select an SSL library according to the
   <literal>--with-mongodb-ssl</literal> <literal>configure</literal> 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.
  </para>

  <note>
   <para>
    If the build process fails to find an SSL library, check that the
    development packages (e.g. <literal>libssl-dev</literal>) and
    <link xlink:href="&url.mongodb.wiki.pkg-config;">pkg-config</link> are both
    installed.
   </para>

   <para>
    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 <literal>PKG_CONFIG_PATH</literal> environment variable may
    be used to control the search path for <literal>pkg-config</literal>.
   </para>
  </note>

  <para>
   The final build step, <command>make install</command>, will report where
   <filename>mongodb.so</filename> has been installed, similar to:
   <programlisting role="txt">
<![CDATA[
Installing shared extensions:     /usr/lib/php/extensions/debug-non-zts-20220829/
]]>
   </programlisting>
  </para>

  <para>
   Ensure that the <link linkend="ini.extension-dir">extension_dir</link> option
   in &php.ini; points to the directory where <filename>mongodb.so</filename>
   was installed. The option may be queried by running:
   <programlisting role="shell">
<![CDATA[
$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
                   /usr/lib/php/extensions/debug-non-zts-20220829
]]>
   </programlisting>
  </para>

  <para>
   If the directories differ, either change
   <link linkend="ini.extension-dir">extension_dir</link> in &php.ini; or
   manually move <filename>mongodb.so</filename> to the correct directory.
  </para>

  <para>
   Finally, add the following line to the &php.ini; file for each environment
   that will need to use the extension:
   <programlisting role="ini">
<![CDATA[
extension=mongodb.so
]]>
   </programlisting>
  </para>
 </section>

</section>


<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->