Installation of PECL extensions

Pie

Introduction to PECL Installations

Pie

Pecl is a repository of PHP extensions that are made available via the PEAR packaging system. This section of the manual is intended to demonstrate how to obtain and install PECL extensions.

These instructions assume /path/to/php/src/dir/ is the path to the PHP source distribution and that extname is the name of the PECL extension. Adjust accordingly. These instructions also assume a familiarity with the pear command. The information in the PEAR manual for the pear command also applies to the pecl command.

A shared extension must be built, installed, and loaded to be useful. The methods described below provide various instructions on how to build and install the extensions, but they do not automatically load them. Extensions can be loaded by adding an extension directive to the Ini file or through the use of the dl() function.

When building PHP modules, it's important to have known-good versions of the required tools (autoconf, automake, libtool, etc.). See the Anonymous Git Instructions for details on the required tools and required versions.

Downloading PECL extensions

Pie

There are several options for downloading PECL extensions, such as:

• The pecl install extname command downloads the extensions code automatically, so in this case, there is no need for a separate download.

• Pecl

  The PECL website contains information about the different extensions that are offered by the PHP Development Team. The information available here includes: changelog, release notes, requirements, and other similar details.

• pecl download extname

  PECL extensions that have releases listed on the PECL website are available for download and installation using the pecl command. Specific revisions may also be specified.

• git

  Many PECL extensions reside on GitHub.

• SVN

  Some PECL extensions also reside in SVN. A web-based view may be seen at Svnpecl/. To download straight from SVN, the following sequence of commands may be used:

  output

  $ svn checkout https://svn.php.net/repository/pecl/extname/trunk extname

• Windows downloads

  The PHP project compiles and offers Windows DLLs for most PECL extensions on the package page.

Installing a PHP extension on Windows

Pie

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:

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 Ini configuration file. Please note that many extensions are already present in the 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 Ini located alongside the PHP executable. To find out where the actual 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 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 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.

Compiling shared PECL extensions with the pecl command

Pie

PECL makes it easy to create shared PHP extensions. Using the pecl command, do the following:

$ pecl install extname

This will download the source for extname, compile, and install extname.so into the extension_dir. extname.so may then be loaded via Ini.

By default, the pecl command will not install packages that are marked with the alpha or beta state. If no stable packages are available, a beta package may be installed using the following command:

$ pecl install extname-beta

A specific version may also be installed using this variant:

$ pecl install extname-0.1

Compiling shared PECL extensions with phpize

Pie

Sometimes, using the pecl installer is not an option. This could be because there is a firewall or because the extension being installed is unavailable as a PECL-compatible package, such as unreleased extensions from git. If such an extension needs to be built, the lower-level build tools can be used to perform the build manually.

The phpize command is used to prepare the build environment for a PHP extension. In the following sample, the sources for an extension are in a directory named extname:

$ cd extname
$ phpize
$ ./configure
$ make
# make install

A successful install will have created extname.so and put it into the PHP extensions directory. The Ini will need to be adjusted, and an extension=extname.so line will need to be added before the extension can be used.

If the system is missing the phpize command, and precompiled packages (like RPM's) are used, be sure to install also the appropriate development version of the PHP package as they often include the phpize command along with the proper header files to build PHP and its extensions.

Execute phpize --help to display additional usage information.

php-config

Pie

php-config is a simple shell script for obtaining information about the installed PHP configuration.

When the extensions are being compiled, if multiple PHP versions are installed, the installation for which to build can be specified by using the --with-php-config option during configuration, setting the path of the respective php-config script.

The list of command line options provided by the php-config script can be queried anytime by running php-config with the -h switch:

Usage: /usr/local/bin/php-config [OPTION]
Options:
  --prefix            [...]
  --includes          [...]
  --ldflags           [...]
  --libs              [...]
  --extension-dir     [...]
  --include-dir       [...]
  --php-binary        [...]
  --php-sapis         [...]
  --configure-options [...]
  --version           [...]
  --vernum            [...]

Compiling PECL extensions statically into PHP

Pie

It may be necessary to build a PECL extension statically into the PHP binary. To do this, the extension source will need to be placed under the /path/to/php/src/dir/ext/ directory, and the PHP build system will be required to regenerate its configure script.

$ cd /path/to/php/src/dir/ext
$ pecl download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname

This will result in the following directory:

/path/to/php/src/dir/ext/extname

From here, PHP needs to be forced to rebuild the configure script, and then it can be built as normal:

$ cd /path/to/php/src/dir
$ rm configure
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install

Whether --enable-extname or --with-extname is used depends on the extension. Typically, an extension that does not require external libraries uses --enable. To be sure, run the following after buildconf:

$ ./configure --help | grep extname