Installation of PECL extensions Introduction to PECL Installations PECL is a repository of PHP extensions that are made available to you via the PEAR packaging system. This section of the manual is intended to demonstrate how to obtain and install PECL extensions. These instructions assume /your/phpsrcdir/ 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. To be useful, a shared extension must be built, installed, and loaded. The methods described below provide you with 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 &php.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 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. &url.pecl; The PECL web site 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 web site are available for download and installation using the pecl command. Specific revisions may also be specified. SVN Most PECL extensions also reside in SVN. A web-based view may be seen at &url.php.svn;pecl/. To download straight from SVN, the following sequence of commands may be used: $ svn checkout http://svn.php.net/repository/pecl/extname/trunk extname Windows downloads The PHP project compiles and offers Windows DLLs for most PECL extensions on the respective package page. Installing a PHP extension on Windows On Windows, you have two ways to load a PHP extension: either compile it into PHP, or load the DLL. Loading a pre-compiled extension is the easiest and preferred way. To load an extension, you need to have it available as a ".dll" file on your 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 building from source documentation. To compile a standalone extension (aka a DLL file), please refer to building from source documentation. If the DLL file is available neither with your PHP distribution nor in PECL, you may have to compile it before you can start using the extension. 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 "core" extensions. However, if you need functionality not provided by any core extension, you may still be able to find one 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 development of PHP extensions. If you have developed an extension for your own uses, you might want to think about hosting it on PECL so that others with the same needs can benefit from your time. A nice side effect is that you give them a good chance to give you feedback, (hopefully) thanks, bug reports and even fixes/patches. Before you submit your extension for hosting on PECL, please read PECL submit. Which extension to download? Many times, you will find several versions of each DLL: Different version numbers (at least the first two numbers should match) Different thread safety settings Different processor architecture (x86, x64, ...) Different debugging settings etc. You should keep in mind that your extension settings should match all the settings of the PHP executable you are using. The following PHP script will tell you all about your PHP settings: <function>phpinfo</function> call ]]> Or from the command line, run: Loading an extension The most common way to load a PHP extension is to include it in your php.ini configuration file. Please note that many extensions are already present in your php.ini and that you only need to remove the semicolon to activate them. Note that, on PHP version 7.2.0 and up, 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. However, some web servers are confusing because they do not use the php.ini located alongside your PHP executable. To find out where your actual php.ini resides, look for its path in phpinfo: 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, you should check your logs to learn where the problem comes from. If you are using PHP from the command line (CLI), the extension loading error can be read directly on screen. If you are using PHP with a web server, the location and format of the logs vary depending on your software. Please read your web server documentation to locate the logs, as it does not have anything to do with PHP itself. Common problems are the location of the DLL, 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, you probably didn't download the right DLL. Try downloading again the extension with the right settings. Again, phpinfo can be of great help. Compiling shared PECL extensions with the pecl command 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 your extension_dir. extname.so may then be loaded via &php.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, you may install a beta package using the following command: $ pecl install extname-beta You may also install a specific version using this variant: $ pecl install extname-0.1 After enabling the extension in &php.ini;, restarting the web service is required for the changes to be picked up. Compiling shared PECL extensions with phpize Sometimes, using the pecl installer is not an option. This could be because you're behind a firewall, or it could be because the extension you want to install is not available as a PECL compatible package, such as unreleased extensions from SVN. If you need to build such an extension, you can use the lower-level build tools 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: A successful install will have created extname.so and put it into the PHP extensions directory. You'll need to and adjust &php.ini; and add an extension=extname.so line before you can use the extension. If the system is missing the phpize command, and precompiled packages (like RPM's) are used, be sure to also install the appropriate devel version of the PHP package as they often include the phpize command along with the appropriate header files to build PHP and its extensions. Execute phpize --help to display additional usage information. php-config php-config is a simple shell script for obtaining information about the installed PHP configuration. When compiling extensions, if you have multiple PHP versions installed, you may specify for which installation you'd like to build by using the --with-php-config option during configuration, specifying 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 switch: Command line options Option Description --prefix Directory prefix where PHP is installed, e.g. /usr/local --includes List of -I options with all include files --ldflags LD Flags which PHP was compiled with --libs Extra libraries which PHP was compiled with --extension-dir Directory where extensions are searched by default --include-dir Directory prefix where header files are installed by default --php-binary Full path to php CLI or CGI binary --php-sapis Show all SAPI modules available --configure-options Configure options to recreate configuration of current PHP installation --version PHP version --vernum PHP version as integer
Compiling PECL extensions statically into PHP You might find that you need to build a PECL extension statically into your PHP binary. To do this, you'll need to place the extension source under the /your/phpsrcdir/ext/ directory and tell the PHP build system to regenerate its configure script. This will result in the following directory: /your/phpsrcdir/ext/extname From here, force PHP to rebuild the configure script, and then build PHP as normal: $ cd /your/phpsrcdir $ rm configure $ ./buildconf --force $ ./configure --help $ ./configure --with-extname --enable-someotherext --with-foobar $ make $ make install To run the 'buildconf' script you need autoconf 2.13 and automake 1.4+ (newer versions of autoconf may work, but are not supported). 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