PHPLIB-790: Docs for common extension install errors

Author: jmikola

docs/tutorial/install-php-library.txt

@@ -50,21 +50,9 @@ your ``php.ini`` file:
 
    extension=php_mongodb.dll
 
-Windows binaries are available for various combinations of PHP version,
-thread-safety, and architecture. Failure to select the correct binary will
-result in an error attempting to load the extension DLL at runtime. Additional
-considerations for Windows are discussed in the
+Additional considerations for Windows are discussed in the
 :php:`Windows installation documentation <manual/en/mongodb.installation.windows.php>`.
 
-.. note::
-
-   If your system has multiple versions of PHP installed, each version will have
-   its own ``pecl`` command and ``php.ini`` file. Additionally, PHP may also use
-   separate ``php.ini`` files for its web and CLI environments. If the extension
-   has been installed but is not available at runtime, double-check that you
-   have used the correct ``pecl`` command (or binary in the case of Windows) and
-   have modified the appropriate ``php.ini`` file(s).
-
 Installing the Library
 ----------------------
 
@@ -109,3 +97,70 @@ classes *and* functions are loaded for your application:
 #. Regardless of whether you are using an autoloader, manually require the
    ``src/functions.php`` file. This is necessary because PHP does not support
    autoloading for functions.
+
+Common Extension Installation Errors
+------------------------------------
+
+PHP Headers Not Found
+~~~~~~~~~~~~~~~~~~~~~
+
+For example:
+
+.. code-block:: none
+
+   /private/tmp/pear/install/mongodb/php_phongo.c:24:10: fatal error: 'php.h' file not found
+
+   #include <php.h>
+            ^~~~~~~
+
+This error indicates that PHP's build system cannot find the necessary headers.
+All PHP extensions require headers in order to compile. Additionally, those
+headers must correspond to the PHP runtime for which the extension will be used.
+Generally, the ``phpize`` command (invoked by ``pecl``) will ensure that the
+extension builds with the correct headers.
+
+Note that the mere presence of a PHP runtime does not mean that headers are
+available. On various Linux distributions, headers are often published under a
+separate ``php-dev`` or ``php-devel`` package. On macOS, the default PHP runtime
+does not include headers and users typically need to install PHP (and headers)
+via `Homebrew <https://brew.sh/>`_ in order to build an extension.
+
+Multiple PHP Runtimes Installed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your system has multiple versions of PHP installed, each version will have
+its own ``pecl`` and ``phpize`` commands. Additionally, each PHP runtime may
+have separate ``php.ini`` files for each SAPI (e.g. FPM, CLI). If the extension
+has been installed but is not available at runtime, double-check that you have
+used the correct ``pecl`` command and have modified the appropriate ``php.ini``
+file(s).
+
+If there is any doubt about the ``php.ini`` file being used by a PHP runtime,
+you should examine the output of :php:`phpinfo() <phpinfo>` for that particular
+SAPI. Additionally, :php:`php_ini_loaded_file() <php_ini_loaded_file>` and
+:php:`php_ini_scanned_files() <php_ini_scanned_files>` may be used to determine
+exactly which INI files have been loaded by PHP.
+
+Loading an Incompatible DLL on Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PECL builds Windows binaries for various combinations of PHP version,
+thread-safety (TS or NTS), and architecture (x86 or x64). Failure to select the
+correct binary will result in an error when attempting to load the extension DLL
+at runtime:
+
+.. code-block:: none
+
+   PHP Warning:  PHP Startup: Unable to load dynamic library 'mongodb'
+
+Ensure that you have downloaded a DLL that corresponds to the following PHP
+runtime properties:
+
+- PHP version (``PHP_VERSION``)
+- Thread-safety (``PHP_ZTS``)
+- Architecture (``PHP_INT_SIZE``)
+
+In addition to the aforementioned constants, these properties can also be
+inferred from :php:`phpinfo() <phpinfo>`. If your system has multiple PHP
+runtimes installed, double-check that you are examining the ``phpinfo()`` output
+for the correct environment.