Skip to content

Commit 16826e5

Browse files
jmikolajmikola
committed
PHPLIB-790: Move extension install errors to FAQ
1 parent c8aa4af commit 16826e5

File tree

3 files changed

+79
-67
lines changed

3 files changed

+79
-67
lines changed

‎docs/faq.txt

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
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.

‎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/install-php-library.txt

Lines changed: 0 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -97,70 +97,3 @@ classes *and* functions are loaded for your application:
9797
#. Regardless of whether you are using an autoloader, manually require the
9898
``src/functions.php`` file. This is necessary because PHP does not support
9999
autoloading for functions.
100-
101-
Common Extension Installation Errors
102-
------------------------------------
103-
104-
PHP Headers Not Found
105-
~~~~~~~~~~~~~~~~~~~~~
106-
107-
For example:
108-
109-
.. code-block:: none
110-
111-
/private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
112-
113-
#include <php.h>
114-
^~~~~~~
115-
116-
This error indicates that PHP's build system cannot find the necessary headers.
117-
All PHP extensions require headers in order to compile. Additionally, those
118-
headers must correspond to the PHP runtime for which the extension will be used.
119-
Generally, the ``phpize`` command (invoked by ``pecl``) will ensure that the
120-
extension builds with the correct headers.
121-
122-
Note that the mere presence of a PHP runtime does not mean that headers are
123-
available. On various Linux distributions, headers are often published under a
124-
separate ``php-dev`` or ``php-devel`` package. On macOS, the default PHP runtime
125-
does not include headers and users typically need to install PHP (and headers)
126-
via `Homebrew <https://brew.sh/>`_ in order to build an extension.
127-
128-
Multiple PHP Runtimes Installed
129-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
130-
131-
If your system has multiple versions of PHP installed, each version will have
132-
its own ``pecl`` and ``phpize`` commands. Additionally, each PHP runtime may
133-
have separate ``php.ini`` files for each SAPI (e.g. FPM, CLI). If the extension
134-
has been installed but is not available at runtime, double-check that you have
135-
used the correct ``pecl`` command and have modified the appropriate ``php.ini``
136-
file(s).
137-
138-
If there is any doubt about the ``php.ini`` file being used by a PHP runtime,
139-
you should examine the output of :php:`phpinfo() <phpinfo>` for that particular
140-
SAPI. Additionally, :php:`php_ini_loaded_file() <php_ini_loaded_file>` and
141-
:php:`php_ini_scanned_files() <php_ini_scanned_files>` may be used to determine
142-
exactly which INI files have been loaded by PHP.
143-
144-
Loading an Incompatible DLL on Windows
145-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146-
147-
PECL builds Windows binaries for various combinations of PHP version,
148-
thread-safety (TS or NTS), and architecture (x86 or x64). Failure to select the
149-
correct binary will result in an error when attempting to load the extension DLL
150-
at runtime:
151-
152-
.. code-block:: none
153-
154-
PHP Warning: PHP Startup: Unable to load dynamic library 'mongodb'
155-
156-
Ensure that you have downloaded a DLL that corresponds to the following PHP
157-
runtime properties:
158-
159-
- PHP version (``PHP_VERSION``)
160-
- Thread-safety (``PHP_ZTS``)
161-
- Architecture (``PHP_INT_SIZE``)
162-
163-
In addition to the aforementioned constants, these properties can also be
164-
inferred from :php:`phpinfo() <phpinfo>`. If your system has multiple PHP
165-
runtimes installed, double-check that you are examining the ``phpinfo()`` output
166-
for the correct environment.

0 commit comments

Comments
 (0)