PHP CookBook

Recipe 21.6 Installing PECL Packages

21.6.1 Problem

You want to install a PECL package; this builds a PHP extension written in C to use inside PHP.

21.6.2 Solution

Make sure you have all the necessary extension libraries and then use the PEAR package manager install command:

% pear install xmms

To use the extension from PHP, load it using dl( ):

dl('xmms.so');

21.6.3 Discussion

The frontend process for installing PECL packages is just like installing PEAR packages for code written in PHP. However, the behind-the-scenes tasks are very different. Because PECL extensions are written in C, the package manager needs to compile the extension and configure it to work with the installed version of PHP. As a result, at present, you can build PECL packages on Unix machines and on Windows machines if you use MSDev.

Unlike PHP-based PEAR packages, PECL extensions don't automatically inform you when you lack a library necessary to compile the extension. Instead, you are responsible for correctly preinstalling these files. If you are having trouble getting a PECL extension to build, check the README file and the other documentation that comes with the package. The package manager installs these files inside the docs directory under your PEAR hierarchy.

When you install a PECL extension, the PEAR package manager downloads the file, extracts it, runs phpize to configure the extension for the version of PHP installed on the machine, and then makes and installs the extension. It may also prompt you for the location of libraries:

% pear install xmms
downloading xmms-0.2.tgz ...
...done: 11,968 bytes
4 source files, building
running: phpize
PHP Api Version        : 20020307
Zend Module Api No     : 20020429
Zend Extension Api No  : 20020731
Xmms library install dir? [autodetect] : 
building in /var/tmp/pear-build-adam/xmms-0.2
running: /tmp/pearKIv63P/xmms-0.2/configure --with-xmms
running: make
xmms.so copied to /tmp/pearKIv63P/xmms-0.2/xmms.so
install ok: xmms 0.2

If these libraries are in a standard location, hitting Return selects the autodetect option. PHP then searches for the libraries and selects them; you don't need to enter an explicit pathname, as in the case of the xmms library shown earlier.

PECL extensions are stored in different places than non-PECL packages. If you want to run pear, you must be able to write inside the PHP extensions directory. Some PECL packages, such as xmms, install files in the same directory as the PHP binary. Because of this, you may want to install these packages while running as the same user you used to install PHP. Also, check the execute permissions of these files; because most PEAR files aren't executable, your umask may not provide those executable files with the correct set of permissions.

21.6.4 See Also

Recipe 21.5 for information on installing PEAR packages; Recipe 21.7 for more on upgrading an existing package; Recipe 21.8 to uninstall a package.