Skip to content

Commit c8f1188

Browse files
jmikolajmikola
authored
PHPLIB-790: Docs for common troubleshooting issues (#982)
* Clarify how batchSize option applies to aggregate and getMore * FAQ for common extension install errors * Server selection tutorial and FAQ entry * PHPLIB-937: Clarify install steps when not using Composer * Fix indentation for list in GridFS tutorial
1 parent b5365c8 commit c8f1188

File tree

8 files changed

+376
-40
lines changed

8 files changed

+376
-40
lines changed

‎docs/faq.txt

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
==========================
2+
Frequently Asked Questions
3+
==========================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Common Extension Installation Errors
14+
------------------------------------
15+
16+
PHP Headers Not Found
17+
~~~~~~~~~~~~~~~~~~~~~
18+
19+
For example:
20+
21+
.. code-block:: none
22+
23+
/private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
24+
25+
#include <php.h>
26+
^~~~~~~
27+
28+
This error indicates that PHP's build system cannot find the necessary headers.
29+
All PHP extensions require headers in order to compile. Additionally, those
30+
headers must correspond to the PHP runtime for which the extension will be used.
31+
Generally, the ``phpize`` command (invoked by ``pecl``) will ensure that the
32+
extension builds with the correct headers.
33+
34+
Note that the mere presence of a PHP runtime does not mean that headers are
35+
available. On various Linux distributions, headers are often published under a
36+
separate ``php-dev`` or ``php-devel`` package. On macOS, the default PHP runtime
37+
does not include headers and users typically need to install PHP (and headers)
38+
via `Homebrew <https://brew.sh/>`_ in order to build an extension.
39+
40+
Multiple PHP Runtimes Installed
41+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42+
43+
If your system has multiple versions of PHP installed, each version will have
44+
its own ``pecl`` and ``phpize`` commands. Additionally, each PHP runtime may
45+
have separate ``php.ini`` files for each SAPI (e.g. FPM, CLI). If the extension
46+
has been installed but is not available at runtime, double-check that you have
47+
used the correct ``pecl`` command and have modified the appropriate ``php.ini``
48+
file(s).
49+
50+
If there is any doubt about the ``php.ini`` file being used by a PHP runtime,
51+
you should examine the output of :php:`phpinfo() <phpinfo>` for that particular
52+
SAPI. Additionally, :php:`php_ini_loaded_file() <php_ini_loaded_file>` and
53+
:php:`php_ini_scanned_files() <php_ini_scanned_files>` may be used to determine
54+
exactly which INI files have been loaded by PHP.
55+
56+
Loading an Incompatible DLL on Windows
57+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58+
59+
PECL builds Windows binaries for various combinations of PHP version,
60+
thread-safety (TS or NTS), and architecture (x86 or x64). Failure to select the
61+
correct binary will result in an error when attempting to load the extension DLL
62+
at runtime:
63+
64+
.. code-block:: none
65+
66+
PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
67+
68+
Ensure that you have downloaded a DLL that corresponds to the following PHP
69+
runtime properties:
70+
71+
- PHP version (``PHP_VERSION``)
72+
- Thread-safety (``PHP_ZTS``)
73+
- Architecture (``PHP_INT_SIZE``)
74+
75+
In addition to the aforementioned constants, these properties can also be
76+
inferred from :php:`phpinfo() <phpinfo>`. If your system has multiple PHP
77+
runtimes installed, double-check that you are examining the ``phpinfo()`` output
78+
for the correct environment.
79+
80+
Server Selection Failures
81+
-------------------------
82+
83+
The follow are all examples of
84+
:doc:`Server Selection </tutorial/server-selection>` failures:
85+
86+
.. code-block:: none
87+
88+
No suitable servers found (`serverSelectionTryOnce` set):
89+
[connection refused calling hello on 'a.example.com:27017']
90+
[connection refused calling hello on 'b.example.com:27017']
91+
92+
No suitable servers found: `serverSelectionTimeoutMS` expired:
93+
[socket timeout calling hello on 'example.com:27017']
94+
95+
No suitable servers found: `serverSelectionTimeoutMS` expired:
96+
[connection timeout calling hello on 'a.example.com:27017']
97+
[connection timeout calling hello on 'b.example.com:27017']
98+
[TLS handshake failed: -9806 calling hello on 'c.example.com:27017']
99+
100+
No suitable servers found: `serverselectiontimeoutms` timed out:
101+
[TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'a.example.com:27017']
102+
[TLS handshake failed: certificate verify failed (64): IP address mismatch calling hello on 'b.example.com:27017']
103+
104+
These errors typically manifest as a
105+
:php:`MongoDB\\Driver\\Exception\\ConnectionTimeoutException <mongodb-driver-exception-connectiontimeoutexception>`
106+
exception from the driver. The actual exception messages originate from
107+
libmongoc, which is the underlying library used by the PHP driver. Since these
108+
messages can take many forms, it's helpful to break down the structure of the
109+
message so you can better diagnose errors in your application.
110+
111+
Messages will typically start with "No suitable servers found". The next part of
112+
the message indicates *how* server selection failed. By default, the PHP driver
113+
avoids a server selection loop and instead makes a single attempt (according to
114+
the ``serverSelectionTryOnce`` connection string option). If the driver is
115+
configured to utilize a loop, a message like "serverSelectionTimeoutMS expired"
116+
will tell us that we exhausted its time limit.
117+
118+
The last component of the message tells us *why* server selection failed, and
119+
includes one or more errors directly from the topology scanner, which is the
120+
service responsible for connecting to and monitoring each host. Any host that
121+
last experienced an error during monitoring will be included in this list. These
122+
messages typically originate from low-level socket or TLS functions.
123+
124+
The following is not meant to be exhaustive, but will hopefully point you in the
125+
right direction for analyzing the contributing factor(s) for a server selection
126+
failure:
127+
128+
- "connection refused" likely indicates that the remote host is not listening on
129+
the expected port.
130+
- "connection timeout" could indicate a routing or firewall issue, or perhaps
131+
a timeout due to latency.
132+
- "socket timeout" suggests that a connection *was* established at some point
133+
but was dropped or otherwise timeout out due to latency.
134+
- "TLS handshake failed" suggests something related to TLS or OCSP verification
135+
and is sometimes indicative of misconfigured TLS certificates.

‎docs/includes/apiargs-aggregate-option.yaml

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,14 @@ arg_name: option
1212
name: batchSize
1313
type: integer
1414
description: |
15-
Specifies the initial batch size for the cursor. A batchSize of ``0`` means an
16-
empty first batch and is useful for quickly returning a cursor or failure
17-
message without doing significant server-side work.
15+
Specifies the batch size for the cursor, which will apply to both the initial
16+
``aggregate`` command and any subsequent ``getMore`` commands. This determines
17+
the maximum number of documents to return in each response from the server.
18+
19+
A batchSize of ``0`` is special in that and will only apply to the initial
20+
``aggregate`` command; subsequent ``getMore`` commands will use the server's
21+
default batch size. This may be useful for quickly returning a cursor or
22+
failure from ``aggregate`` without doing significant server-side work.
1823
interface: phpmethod
1924
operation: ~
2025
optional: true

‎docs/includes/apiargs-method-watch-option.yaml

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,17 @@ arg_name: option
33
name: batchSize
44
type: integer
55
description: |
6-
Specifies the maximum number of change events to return in each batch of the
7-
response from the MongoDB cluster.
6+
Specifies the batch size for the cursor, which will apply to both the initial
7+
``aggregate`` command and any subsequent ``getMore`` commands. This determines
8+
the maximum number of change events to return in each response from the
9+
server.
10+
11+
.. note::
12+
13+
Irrespective of the ``batchSize`` option, the initial ``aggregate`` command
14+
response for a change stream generally does not include any documents
15+
unless another option is used to configure its starting point (e.g.
16+
``startAfter``).
817
interface: phpmethod
918
operation: ~
1019
optional: true

‎docs/index.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,3 +66,4 @@ encounter in the library documentation:
6666
/tutorial
6767
/upgrade
6868
/reference
69+
FAQ </faq>

‎docs/tutorial.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Tutorials
66
.. toctree::
77

88
/tutorial/connecting
9+
/tutorial/server-selection
910
/tutorial/crud
1011
/tutorial/collation
1112
/tutorial/commands

‎docs/tutorial/gridfs.txt

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@ method.
2828

2929
The bucket can be constructed with various options:
3030

31-
- ``bucketName`` determines the prefix for the bucket's metadata and chunk
32-
collections. The default value is ``"fs"``.
33-
- ``chunkSizeBytes`` determines the size of each chunk. GridFS divides the
34-
file into chunks of this length, except for the last, which is only as large
35-
as needed. The default size is ``261120`` (i.e. 255 KiB).
36-
- ``readConcern``, ``readPreference`` and ``writeConcern`` options can be used
37-
to specify defaults for read and write operations, much like the
38-
:phpclass:`MongoDB\\GridFS\\Collection` options.
31+
- ``bucketName`` determines the prefix for the bucket's metadata and chunk
32+
collections. The default value is ``"fs"``.
33+
- ``chunkSizeBytes`` determines the size of each chunk. GridFS divides the file
34+
into chunks of this length, except for the last, which is only as large as
35+
needed. The default size is ``261120`` (i.e. 255 KiB).
36+
- ``readConcern``, ``readPreference`` and ``writeConcern`` options can be used
37+
to specify defaults for read and write operations, much like the
38+
:phpclass:`MongoDB\\GridFS\\Collection` options.
3939

4040
Uploading Files with Writable Streams
4141
-------------------------------------

‎docs/tutorial/install-php-library.txt

Lines changed: 20 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -50,24 +50,15 @@ your ``php.ini`` file:
5050

5151
extension=php_mongodb.dll
5252

53-
Windows binaries are available for various combinations of PHP version,
54-
thread-safety, and architecture. Failure to select the correct binary will
55-
result in an error attempting to load the extension DLL at runtime. Additional
56-
considerations for Windows are discussed in the
53+
Additional considerations for Windows are discussed in the
5754
:php:`Windows installation documentation <manual/en/mongodb.installation.windows.php>`.
5855

59-
.. note::
60-
61-
If your system has multiple versions of PHP installed, each version will have
62-
its own ``pecl`` command and ``php.ini`` file. Additionally, PHP may also use
63-
separate ``php.ini`` files for its web and CLI environments. If the extension
64-
has been installed but is not available at runtime, double-check that you
65-
have used the correct ``pecl`` command (or binary in the case of Windows) and
66-
have modified the appropriate ``php.ini`` file(s).
67-
6856
Installing the Library
6957
----------------------
7058

59+
Using Composer
60+
~~~~~~~~~~~~~~
61+
7162
The preferred method of installing the |php-library| is with
7263
`Composer <https://getcomposer.org/>`_ by running the following command from
7364
your project root:
@@ -76,13 +67,6 @@ your project root:
7667

7768
composer require mongodb/mongodb
7869

79-
While not recommended, you may also manually install the library using a source
80-
archive attached to the
81-
`GitHub releases <https://github.com/mongodb/mongo-php-library/releases>`_.
82-
83-
Configure Autoloading
84-
~~~~~~~~~~~~~~~~~~~~~
85-
8670
Once you have installed the library, ensure that your application includes
8771
Composer's autoloader as in the following example:
8872

@@ -96,11 +80,20 @@ Refer to Composer's `autoloading documentation
9680
<https://getcomposer.org/doc/01-basic-usage.md#autoloading>`_ for more
9781
information about setting up autoloading.
9882

99-
If you installed the library manually from a source archive, you will need to
100-
manually configure autoloading:
101-
102-
#. Map the top-level ``MongoDB\`` namespace to the ``src/`` directory
103-
using your preferred autoloader implementation.
83+
Manual Installation Without Composer
84+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10485

105-
#. Manually require the ``src/functions.php`` file. This is necessary because
106-
PHP does not support autoloading for functions.
86+
While not recommended, you may also manually install the library using a source
87+
archive attached to the
88+
`GitHub releases <https://github.com/mongodb/mongo-php-library/releases>`_. When
89+
installing the library without Composer, you must ensure that all library
90+
classes *and* functions are loaded for your application:
91+
92+
#. If you are using a `PSR-4 <https://www.php-fig.org/psr/psr-4/>`_ autoloader,
93+
map the top-level ``MongoDB\`` namespace to the ``src/`` directory. If you
94+
are not using an autoloader, manually require _all_ class files found
95+
recursively within the ``src/`` directory.
96+
97+
#. Regardless of whether you are using an autoloader, manually require the
98+
``src/functions.php`` file. This is necessary because PHP does not support
99+
autoloading for functions.

0 commit comments

Comments
 (0)