php-doc-en/reference/mongodb/configure.xml

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

<article 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 Driver 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
   driver:
   <programlisting role="shell">
<![CDATA[
$ sudo pecl install mongodb
]]>
   </programlisting>
  </para>

  <para>
   If your system has multiple version of PHP installed (e.g. macOS default,
   Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), note that that each
   version of PHP has its own <link linkend="install.pecl">pecl</link>
   command and &php.ini; file.
  </para>

  <para>
   Installing the driver via PECL will use bundled versions of
   <link xlink:href="&url.mongodb.libbson;">libbson</link> and
   <link xlink:href="&url.mongodb.libmongoc;">libmongoc</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 your &php.ini; file:
   <programlisting role="ini">
<![CDATA[
extension=mongodb.so
]]>
   </programlisting>
  </para>
 </section>

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

  <para>
   <link xlink:href="https://brew.sh/2018/01/19/homebrew-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="https://formulae.brew.sh/formula/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>
 </section>

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

  <para>
   Precompiled binaries for each release are available from
   <link xlink:href="&url.pecl.package;mongodb">PECL</link> for a variety of
   combinations of versions, thread safety, and VC libraries. Extract the
   archive and put <filename>php_mongodb.dll</filename> in your PHP extension
   directory ("ext" by default).
  </para>

  <para>
   Add the following line to your &php.ini; file:
   <programlisting role="ini">
<![CDATA[
extension=php_mongodb.dll
]]>
   </programlisting>
  </para>
 </section>

 <section xml:id="mongodb.installation.manual">
  <title>Manually Installing the MongoDB PHP Driver</title>

  <para>
   For driver developers and people interested in the latest bugfixes, you can
   compile the driver from the latest source code on
   <link xlink:href="&url.mongodb.github;">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>
   If your system has multiple version of PHP installed (e.g. macOS default
   <emphasis>and</emphasis> <link xlink:href="&url.xampp;">XAMPP</link>), note
   that each version of PHP has its own
   <link linkend="install.pecl.phpize">phpize</link> command and &php.ini; file.
  </para>

  <para>
   By default, the driver will use bundled versions of
   <link xlink:href="&url.mongodb.libbson;">libbson</link> and
   <link xlink:href="&url.mongodb.libmongoc;">libmongoc</link> and attempt to
   configure them on its own. If libbson and libmongoc are already installed as
   system libraries, you can instruct the driver to utilize them by specifying
   <literal>--with-libbson=yes --with--libmongoc=yes</literal> as arguments 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 libbson and libmongoc, the driver will also
   attempt to select an SSL library according to the
   <literal>--with-mongodb-ssl</literal> option for
   <literal>configure</literal>. The default value is
   <literal>--with-mongodb-ssl=auto</literal>, which will search for Secure
   Transport (macOS only), OpenSSL, and LibreSSL, in that order. Additionally,
   you may specify <literal>openssl</literal>, <literal>libressl</literal>, or
   <literal>darwin</literal> to force selection of a particular library,
   respectively.
  </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>. If
    <literal>pkg-config</literal> is not used, <literal>configure</literal> also
    supports a <literal>--with-openssl-dir=DIR</literal> argument, which can be
    used to specify a manual search path (for OpenSSL only).
   </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-20151012/
]]>
   </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. You can query for the option by running:
   <programlisting role="shell">
<![CDATA[
$ php -i | grep extension_dir
  extension_dir => /usr/lib/php/extensions/debug-non-zts-20151012 =>
                   /usr/lib/php/extensions/debug-non-zts-20151012
]]>
   </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 your &php.ini; file:
   <programlisting role="ini">
<![CDATA[
extension=mongodb.so
]]>
   </programlisting>
  </para>
 </section>

</article>


<!-- 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
-->