mirror of
https://github.com/php/doc-en.git
synced 2026-03-23 23:32:18 +01:00
333 lines
11 KiB
XML
333 lines
11 KiB
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.pie">
|
|
<title>Installing the MongoDB PHP Extension with PIE</title>
|
|
|
|
&pecl.moving.to.pie;
|
|
|
|
<para>
|
|
To install the MongoDB extension using PIE, run the following command:
|
|
<programlisting role="shell">
|
|
<![CDATA[
|
|
pie install mongodb/mongodb-extension
|
|
]]>
|
|
</programlisting>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<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
|
|
-->
|