Installing a PHP extension on Windows

There are two ways to load a PHP extension on Windows: either compile it into PHP, or load the DLL. Loading a pre-compiled extension is the easiest and preferred way.

To load an extension, it has to be available as a .dll file on the system. All the extensions are automatically and periodically compiled by the PHP Group (see next section for the download).

To compile an extension into PHP, please refer to the building from source documentation.

To compile a standalone extension (aka a DLL file), please refer to the building from source documentation. If the DLL file is available neither with the PHP distribution nor in PECL, it may be necessary to compile it before the extension can be used.

Where to find an extension?

PHP extensions are usually called php_*.dll (where the star represents the name of the extension), and they are located under the PHP\ext folder.

PHP ships with the extensions most useful to the majority of developers. They are called bundled extensions.

However, if the bundled extensions do not provide the needed functionality, one extension that does may still be found in » PECL. The PHP Extension Community Library (PECL) is a repository for PHP Extensions, providing a directory of all known extensions and hosting facilities for downloading and developing PHP extensions.

If an extension has been developed for particular uses, it may be hosted on PECL so that others with the same needs can benefit from it. A nice side effect is that it's a good chance to receive feedback, (hopefully) thanks, bug reports and even fixes/patches. Before submitting an extension for hosting on PECL, please read » PECL submit.

Which extension to download?

Many times, there will be several versions of each DLL available:

  • Different version numbers (at least the first two numbers should match)
  • Different thread safety settings
  • Different processor architecture (x86, x64, ...)
  • Different debugging settings
  • etc.

Keep in mind that the extension settings should match all the settings of the PHP executable being used. The following PHP script will tell all about the PHP settings:

Example #1 phpinfo() call

<?php
phpinfo
();
?>

Or from the command line, run:

drive:\path\to\php\executable\php.exe -i

Loading an extension

The most common way to load a PHP extension is to include it in the php.ini configuration file. Please note that many extensions are already present in the php.ini and that the semicolon only needs to be removed to activate them.

Note that, as of PHP 7.2.0, the extension name may be used instead of the extension's file name. As this is OS-independent and easier, especially for newcomers, it becomes the recommended way of specifying extensions to load. File names remain supported for compatibility with prior versions.

;extension=php_extname.dll
extension=php_extname.dll
; As of PHP 7.2.0, prefer:
extension=extname
zend_extension=another_extension

However, some web servers are confusing because they do not use the php.ini located alongside the PHP executable. To find out where the actual php.ini resides, look for its path in phpinfo():

Configuration File (php.ini) Path  C:\WINDOWS
Loaded Configuration File   C:\Program Files\PHP\8.2\php.ini

After activating an extension, save php.ini, restart the web server, and check phpinfo() again. The new extension should now have its own section.

Resolving problems

If the extension does not appear in phpinfo(), the logs should be checked to learn where the problem comes from.

If PHP is being used from the command line (CLI), the extension loading error can be read directly on the screen.

If PHP is being used with a web server, the location and format of the logs vary depending on the software. Please read the web server documentation to locate the logs, as it has nothing to do with PHP itself.

Common problems are the location of the DLL and the DLLs it depends on, the value of the "extension_dir" setting inside php.ini and compile-time setting mismatches.

If the problem lies in a compile-time setting mismatch, probably the DLL downloaded is not the right one. Try downloading the extension again with the proper settings. Again, phpinfo() can be of great help.