reference/mongodb/configure.xml
b817c8855866acbb37c260cbc62235b8d2d88ea1
...
...
@@ -23,16 +23,44 @@ $ sudo pecl install mongodb
23
23
</para>
24
24

25
25
<para>
26
-
If your system has multiple version of PHP installed (e.g. macOS default,
27
-
Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), note that that each
28
-
version of PHP has its own <link linkend="install.pecl">pecl</link>
29
-
command and &php.ini; file.
26
+
On systems with multiple version of PHP installed (e.g. macOS default,
27
+
Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), each version of PHP
28
+
will have its own <link linkend="install.pecl">pecl</link>
29
+
command and &php.ini; file(s). Additionally, each PHP environments (e.g.
30
+
CLI, web) may use separate &php.ini; files.
30
31
</para>
31
32

32
33
<para>
33
-
Installing the driver via PECL will use bundled versions of
34
-
<link xlink:href="&url.mongodb.libbson;">libbson</link> and
35
-
<link xlink:href="&url.mongodb.libmongoc;">libmongoc</link> and attempt to
34
+
As of driver version 1.17.0, PECL will prompt for various
35
+
<literal>configure</literal> options. To install the driver with default
36
+
options in a non-interactive script, empty string input may be piped to
37
+
<literal>pecl install</literal> using the <literal>yes</literal> command:
38
+
<programlisting role="shell">
39
+
<![CDATA[
40
+
$ yes '' | sudo pecl install mongodb
41
+
]]>
42
+
</programlisting>
43
+
</para>
44
+

45
+
<para>
46
+
A complete list of supported <literal>configure</literal> options can be
47
+
found in the <literal>package.xml</literal> file included in the PECL
48
+
package. To install the driver with specific <literal>configure</literal>
49
+
options in a non-interactive script, the
50
+
<literal>--configureoptions</literal> option for
51
+
<literal>pecl install</literal> may be used:
52
+
<programlisting role="shell">
53
+
<![CDATA[
54
+
$ sudo pecl install --configureoptions='with-mongodb-system-libs="yes" enable-mongodb-developer-flags="no"' mongodb
55
+
]]>
56
+
</programlisting>
57
+
</para>
58
+

59
+
<para>
60
+
By default, installing the driver via PECL will use bundled versions of
61
+
<link xlink:href="&url.mongodb.libbson;">libbson</link>,
62
+
<link xlink:href="&url.mongodb.libmongoc;">libmongoc</link>, and
63
+
<link xlink:href="&url.mongodb.libmongocrypt;">libmongocrypt</link> and attempt to
36
64
automatically configure them.
37
65
</para>
38
66

...
...
@@ -48,7 +76,8 @@ $ sudo pecl install mongodb
48
76
</note>
49
77

50
78
<para>
51
-
Finally, add the following line to your &php.ini; file:
79
+
Finally, add the following line to the &php.ini; file for each environment
80
+
that will need to use the driver:
52
81
<programlisting role="ini">
53
82
<![CDATA[
54
83
extension=mongodb.so
...
...
@@ -77,15 +106,17 @@ extension=mongodb.so
77
106
<title>Installing the MongoDB PHP Driver on Windows</title>
78
107

79
108
<para>
80
-
Precompiled binaries for each release are available from
81
-
<link xlink:href="&url.pecl.package;mongodb">PECL</link> for a variety of
82
-
combinations of versions, thread safety, and VC libraries. Extract the
83
-
archive and put <filename>php_mongodb.dll</filename> in your PHP extension
84
-
directory ("ext" by default).
109
+
Precompiled binaries are attached to the project's
110
+
<link xlink:href="&url.mongodb.github.new;/releases/">Github releases</link>.
111
+
Archives are published for various combinations of PHP version, thread safety
112
+
(TS or NTS), and architecture (x86 or x64). Determining the correct archive
113
+
for the PHP environment and extract the <filename>php_mongodb.dll</filename>
114
+
file to the extension directory ("ext" by default).
85
115
</para>
86
116

87
117
<para>
88
-
Add the following line to your &php.ini; file:
118
+
Add the following line to the &php.ini; file for each environment that will
119
+
need to use the driver:
89
120
<programlisting role="ini">
90
121
<![CDATA[
91
122
extension=php_mongodb.dll
...
...
@@ -93,6 +124,33 @@ extension=php_mongodb.dll
93
124
</programlisting>
94
125
</para>
95
126

127
+
<para>
128
+
Failure to select the correct binary will result in an error when attempting
129
+
to load the extension DLL at runtime:
130
+
<programlisting role="txt">
131
+
<![CDATA[
132
+
PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
133
+
]]>
134
+
</programlisting>
135
+
</para>
136
+

137
+
<para>
138
+
Ensure that the downloaded DLL corresponds to the following PHP runtime
139
+
properties:
140
+
<simplelist>
141
+
<member>PHP version (<constant>PHP_VERSION</constant>)</member>
142
+
<member>Thread safety (<constant>PHP_ZTS</constant>)</member>
143
+
<member>Architecture (<constant>PHP_INT_SIZE</constant>)</member>
144
+
</simplelist>
145
+
</para>
146
+

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

96
154
<note>
97
155
<title>Additional DLL dependencies for Windows Users</title>
98
156
<para>
...
...
@@ -106,8 +164,8 @@ extension=php_mongodb.dll
106
164
<title>Building the MongoDB PHP Driver from source</title>
107
165

108
166
<para>
109
-
For driver developers and people interested in the latest bugfixes, you can
110
-
compile the driver from the latest source code on
167
+
For driver developers and users interested in the latest bugfixes, the driver
168
+
may be compiled from the latest source code on
111
169
<link xlink:href="&url.mongodb.github.new;">Github</link>. Run the following
112
170
commands to clone and build the project:
113
171
<programlisting role="shell">
...
...
@@ -124,10 +182,11 @@ $ sudo make install
124
182
</para>
125
183

126
184
<para>
127
-
If your system has multiple version of PHP installed (e.g. macOS default
128
-
<emphasis>and</emphasis> <link xlink:href="&url.xampp;">XAMPP</link>), note
129
-
that each version of PHP has its own
130
-
<link linkend="install.pecl.phpize">phpize</link> command and &php.ini; file.
185
+
On systems with multiple version of PHP installed (e.g. macOS default,
186
+
Homebrew, <link xlink:href="&url.xampp;">XAMPP</link>), each version of PHP
187
+
will have its own <link linkend="install.pecl.phpize">phpize</link>
188
+
command and &php.ini; file(s). Additionally, each PHP environments (e.g.
189
+
CLI, web) may use separate &php.ini; files.
131
190
</para>
132
191

133
192
<para>
...
...
@@ -135,12 +194,10 @@ $ sudo make install
135
194
<link xlink:href="&url.mongodb.libbson;">libbson</link>,
136
195
<link xlink:href="&url.mongodb.libmongoc;">libmongoc</link>, and
137
196
<link xlink:href="&url.mongodb.libmongocrypt;">libmongocrypt</link> and
138
-
attempt to configure them on its own. If these libraries are already
139
-
installed as system libraries, you can instruct the driver to utilize them by
140
-
specifying <literal>--with-libbson=yes --with--libmongoc=yes</literal> as
141
-
arguments to <literal>configure</literal>. Starting with version 1.7.0 of the
142
-
extension, these arguments are deprecated and you should use
143
-
<literal>--with-mongodb-system-libs=yes</literal> instead.
197
+
attempt to configure them automatically. If these libraries are already
198
+
installed as system libraries, the driver can utilize them by
199
+
specifying <literal>--with-mongodb-system-libs=yes</literal> as an option to
200
+
<literal>configure</literal>.
144
201
</para>
145
202

146
203
<para>
...
...
@@ -149,15 +206,12 @@ $ sudo make install
149
206
</para>
150
207

151
208
<para>
152
-
When using bundled versions of libbson and libmongoc, the driver will also
153
-
attempt to select an SSL library according to the
154
-
<literal>--with-mongodb-ssl</literal> option for
155
-
<literal>configure</literal>. The default value is
156
-
<literal>--with-mongodb-ssl=auto</literal>, which will search for Secure
157
-
Transport (macOS only), OpenSSL, and LibreSSL, in that order. Additionally,
158
-
you may specify <literal>openssl</literal>, <literal>libressl</literal>, or
159
-
<literal>darwin</literal> to force selection of a particular library,
160
-
respectively.
209
+
When using bundled versions of libmongoc and libmongocrypt, the driver will
210
+
also attempt to select an SSL library according to the
211
+
<literal>--with-mongodb-ssl</literal> <literal>configure</literal> option.
212
+
As of driver version 1.17.0, OpenSSL is always preferred by default.
213
+
Previously, Secure Transport was the default on macOS and OpenSSL was the
214
+
default on all other platforms.
161
215
</para>
162
216

163
217
<note>
...
...
@@ -184,7 +238,7 @@ $ sudo make install
184
238
<filename>mongodb.so</filename> has been installed, similar to:
185
239
<programlisting role="txt">
186
240
<![CDATA[
187
-
Installing shared extensions: /usr/lib/php/extensions/debug-non-zts-20151012/
241
+
Installing shared extensions: /usr/lib/php/extensions/debug-non-zts-20220829/
188
242
]]>
189
243
</programlisting>
190
244
</para>
...
...
@@ -192,12 +246,12 @@ Installing shared extensions: /usr/lib/php/extensions/debug-non-zts-20151012
192
246
<para>
193
247
Ensure that the <link linkend="ini.extension-dir">extension_dir</link> option
194
248
in &php.ini; points to the directory where <filename>mongodb.so</filename>
195
-
was installed. You can query for the option by running:
249
+
was installed. The option may be queried by running:
196
250
<programlisting role="shell">
197
251
<![CDATA[
198
252
$ php -i | grep extension_dir
199
-
extension_dir => /usr/lib/php/extensions/debug-non-zts-20151012 =>
200
-
/usr/lib/php/extensions/debug-non-zts-20151012
253
+
extension_dir => /usr/lib/php/extensions/debug-non-zts-20220829 =>
254
+
/usr/lib/php/extensions/debug-non-zts-20220829
201
255
]]>
202
256
</programlisting>
203
257
</para>
...
...
@@ -209,7 +263,8 @@ $ php -i | grep extension_dir
209
263
</para>
210
264

211
265
<para>
212
-
Finally, add the following line to your &php.ini; file:
266
+
Finally, add the following line to the &php.ini; file for each environment
267
+
that will need to use the driver:
213
268
<programlisting role="ini">
214
269
<![CDATA[
215
270
extension=mongodb.so
216
271



Tools (Romanian Manual)