Installing Homebrew PHP extensions with PECL

Recently the homebrew/php tap was deprecated in favour of PHP versions taken directly from homebrew/core. With this deprecation however, all versions with pre-built extensions were removed. In this guide we'll take a look at how we can compile and add these extensions ourselves.


Prerequisites

For this guide, we’ll asume you’re running a PHP version installed from homebrew/core. If you’re unsure, check what’s installed by running:

$ brew list | grep php

New versions would be listed as:

php ← the latest version, also known as php@7.2
php@5.6
php@7.0
php@7.1

Old versions would be listed as:

php56
php70
php71
php72
php72-memcached
php72-opcache
[...]

If you haven’t made the switch, follow these excellent guides for removing and installing the right version(s).


Installing extensions

The preferred way to install extensions nowadays is through PECL. This can be accomplished with the pecl command.

Install

To install an extension, run the following command.

$ pecl install <extension>

This command will…

  • compile and install the extension in the PECL extension directory
  • add the extension to your currently active PHP configuration (php.ini)

It will not…

  • tell PHP about your PECL extension directory (one-time configuration)

To verify the extension is correcly added in you PHP configuation, run php --ini and open it. The newly installed extension will be on top of the file if you didn’t have an existing extension entry before. Else it will be added below any previously added entry.

The extension is now installed and activated, but at this time PHP still can’t locate the compiled extension itself.

Configure the extension directory

To load extensions installed by PECL, we need to point the extension_dir in our php.ini to the extension directory created by PECL. This directory can be found by running:

$ pecl config-get ext_dir

Now uncomment and update the extension_dir in your php.ini:

extension_dir = /usr/local/lib/php/pecl/<php_api_version>

Verify

After installing an extension you should of course restart your webserver or PHP-FPM instance, depending on how you’re running PHP.

To verify the module is loaded on the CLI, run either:

$ php --info | grep <module>\\.
$ php --modules | grep <module>

If you’re running PHP-FPM, it’s likely the CLI version isn’t the same version as the one running your (web) application. If you want to be sure it’s loading properly, you could create an info.php file, and open it in the browser with these contents:

<?php phpinfo() ?>

Both should show some entries for the newly installed extension.


When running multiple PHP versions

There are two minor caveats to keep in mind when running multiple PHP versions, or switching to a new version.

Different extension directories

Every minor PHP version has its own API version. This means that PECL will have its own extension directory per minor (7.1.*, 7.2.*) PHP version. For example:

/usr/local/lib/php/pecl/20160303 ← 7.1
/usr/local/lib/php/pecl/20170718 ← 7.2

Make sure you don’t mix them up when adding them as the extension_dir in your php.ini. You can always check the current API version by running:

$ php -i | grep 'PHP API'

Compile for each API version

Furthermore, it’s required to compile extensions for every PHP API version. One might think we can cheat the system, and just compile extensions and point all PHP versions to that directory. Trying to do so will result in errors however.

The solution is to switch to the PHP version you want to use, and install the extension again. This will add it to the current version, and will install the compiled extension in the correct API version directory.


An example

As an example, we’ll install the Memcached PHP extension. We use this for communicating with the Memcached daemon, which is a memory caching system comparable to Redis.

Install

To compile the Memcached extension — not to be confused with the outdated Memcache one — we need to install two packages:

$ brew install pkg-config libmemcached

Compile and install the extension:

$ pecl install memcached

Hit return when the installation scripts asks you for the libmemcached path.

Now you’ve installed the memcached extension, provided you’ve pointed your extension_dir to the right path, and restarted your web server or PHP-FPM daemon.

Verify

To verify the module is loaded, run:

$ php --info | grep memcached\\.

It should output a bunch of Memcached-related configuration entries.

Finally

Only thing left is getting Memcached up and running. To install, run:

$ brew install memcached

To start the daemon, launch it with Homebrew Services:

$ brew services start memcached

This will start Memcached, and will also launch it when logging in. To have it run only once, launch it with run instead of start, or use the memcached command for more direct control.

You’re all set. Start caching 💪


Having trouble?

A few paths that might help when having trouble…

PHP installations

/usr/local/opt/php/<version>

PHP configurations

/usr/local/etc/php/<version>

PECL extension directories

/usr/local/lib/php/pecl/<version>