shivammathur/homebrew-extensions: a Homebrew tap for PHP extensions

What a tap of extension formulae actually is

This repository is a Homebrew tap, a third-party repository of formulae that Homebrew can install from, and its content is PHP extensions. The description puts it plainly: a Homebrew tap for PHP extensions.

The value of the approach is that it removes the usual way PECL extensions get installed. Compiling an extension by hand with pecl means finding the right version, having the build dependencies present, and ending up with a copy of the shared object that no other tool knows about. A Homebrew formula wraps all of that, so the extension becomes something with a name, a version and an upgrade path that matches every other tool on the machine.

The detail that makes the tap more than a list of formulae is the versioning. Formulae are named per PHP release, so a package is called [email protected] rather than xdebug, and the README's example installs exactly that. An extension compiled against one PHP version does not load under another, and a system with two PHP versions in play needs two copies of the extension. Homebrew's versioned formula naming is what makes that expressible.

The tap is also the companion to another one from the same author, shivammathur/php, which provides the PHP interpreters themselves. The README says the tap works with PHP from both that tap and homebrew/core, which is a useful piece of interoperability for anyone whose PHP came from elsewhere.

The extension list and its version ranges

The extension table is the substance of the repository, and it runs to around sixty entries. The names map to the extensions PHP developers actually reach for.

The list includes amqp, apcu, ast, brotli, couchbase, decimal, ds, event, excimer, expect, gearman, geos, gmagick, gnupg, grpc, igbinary, imagick, imap, interbase, lua, mailparse, maxminddb, mcrypt, memcache, memcached, mongodb, msgpack, newrelic, oauth, opentelemetry, pcov, pdo_firebird, pdo_sqlsrv, pecl_http, pinba, protobuf, psr, raphf, rdkafka, redis, seaslog, scalar_objects, snmp, sqlsrv, ssh2, spx, swoole, swow, uopz, uploadprogress, uuid, v8js, vips, vld, xdebug, xhprof, xlswriter, yaml, zmq and zstd.

The version ranges are the interesting column, and they are not uniform. Most entries run from PHP 5.6 to PHP 8.7, which is the widest span in the table and reflects the fact that many of these extensions are stable and rarely change.

Others are narrower for a reason. ast, decimal, ds, pdo_firebird, pdo_sqlsrv, pinba, scalar_objects, sqlsrv, v8js, vips, xhprof, xlswriter and zstd start at PHP 7.0, excimer and pcov at 7.1, maxminddb at 7.2, and opentelemetry and swow at 8.0. The Phalcon series is versioned by major, with phalcon3 covering PHP 5.6 to 7.3, phalcon4 from 7.2 to 7.4 and phalcon5 from 7.4 to 8.4, which is what a major-versioned extension looks like in a versioned formula scheme. A few have upper bounds below 8.7, snmp at 8.3, swoole and swow at 8.5, and mongodb1 at 8.6 for PHP 8.1 onward alongside the regular mongodb entry.

So a developer on PHP 5.6 has a smaller menu than one on 8.7, and the table tells you exactly how much smaller before you try.

Platform support and the Intel gap

The OS support table is short and the last line of the README is the one that matters.

Linux on x86_64 is supported. On macOS, the supported systems are Golden Gate, Tahoe and Sequoia, all on arm64. And then: macOS Intel is not supported.

That is a hard boundary rather than a gap in testing, and it reflects where the build infrastructure for the tap runs. The formulae are built for a specific architecture, and Apple Silicon is where the build machines are.

The macOS version list is also a moving target in a way that is easy to miss. The named releases are the current ones, so the list will change as Apple ships new versions of macOS and the tap's support follows. A developer on an older macOS release that is not in the list should check the README rather than assume.

For a Linux user, x86_64 covers the overwhelming majority of servers and desktops, but it does mean that arm64 Linux machines, which are increasingly common, are not covered by that row either. The README does not discuss arm64 Linux, so the honest position is that the tap documents x86_64 Linux and arm64 macOS and says nothing more.

Installing an extension, step by step

The usage section is a sequence of small shell steps, and each one exists for a reason.

The first is to update Homebrew and the formulae.

brew update

Then check the PHP version that is installed, since the formulae are version specific.

php -v

If the right version is not there, the README shows how to get it from the author's PHP tap and link it.

brew tap shivammathur/php
brew install shivammathur/php/[email protected]
brew link --force --overwrite shivammathur/php/[email protected]

The extension tap itself is added and marked trusted, which is a step specific to Homebrew's trust model for third-party taps.

brew tap shivammathur/extensions
brew trust shivammathur/extensions

Then the extension goes in, with the PHP version in the formula name.

brew install shivammathur/extensions/[email protected]

Upgrading follows the same naming, and the README's example is the Xdebug case again.

brew upgrade shivammathur/extensions/[email protected]

The `brew trust` step is the one that stands out. It tells Homebrew to accept formulae from this tap without interactive approval, which is convenient for scripted setup and which also means a decision about which third-party tap to trust permanently. A team automating this across machines should decide that deliberately.

Restarting the webserver, and the debugging checklist

The step that catches people out is the one after the install. If Apache or Nginx is running php-fpm, the webserver has to be restarted after installing or updating any PHP extension, because the extension is a shared object loaded into the running process and a running process does not pick up a newly added one.

brew services restart httpd

brew services restart nginx

The debugging section then gives a short checklist, and its first item is the one that prevents most wasted time: make sure you ran brew update before installing the extension. The second is to run brew doctor and fix the warnings it reports. The third is cut off in the version available here, but the shape of the list suggests the usual suspects, a version mismatch between the formula and the linked PHP, or a missing build dependency.

The general point is that an extension can be installed and still not be doing anything, and the reason is almost always one of three things: the wrong PHP version is linked, the webserver was not restarted, or the extension is installed but not enabled in the php.ini configuration. This tap handles the first two of those by construction, since the formula name carries the version and the README tells you to restart.

How the tap is built and maintained

The repository layout shows an automated pipeline rather than a hand-maintained list. There is a Formula/ directory holding the formulae, plus Abstract/ and Aliases/ directories, and a formula_renames.json file at the root. The formula_renames file is the interesting one, because renaming a formula breaks the brew install command people have in their scripts, and keeping a mapping lets the tap redirect an old name to the new one.

The CI badges at the top of the README name two workflows, Update and Build Formulae and Test Formulae. That is a lot of machinery for a list of formulae, and it is there because a formula that references a PECL tarball has to be rebuilt when the upstream release changes, and because a formula that stops building is a broken formula for everyone using the tap.

The README also links the packages page, which is where the built artefacts are published, and the tap supports PHP versions from 5.6 to 8.7 according to the badge.

The licence is MIT, with the LICENSE file at the root of the repository, and the project is not archived with the last push on 2026-10-16. The recent releases section says there are no GitHub releases, which is normal for a Homebrew tap, since the artefacts live in the packages section and the formulae are updated on the main branch rather than through tagged releases.

Where this tap is the wrong choice

The first limitation is the Intel Mac exclusion. The README says it outright, and it means a developer or CI runner on an Intel Mac cannot use the tap at all. That is a real segment of the PHP developer population, and for them the pecl route or a Linux CI environment is the answer.

The second is that Homebrew on macOS is a user-level package manager. Extensions installed this way live in the Homebrew prefix, not in the system PHP, and the linking steps in the README show how much care that takes. On a Linux server where PHP comes from the distribution's package manager, adding a Homebrew tap to install extensions is an unusual choice, and the tap's Linux support is aimed at developer machines and CI rather than at system packages.

The third is that the version ranges are a moving target that is only documented in the README table. When PHP 8.8 appears, the formulae have to be updated, and until they are, an extension will not install for the new interpreter. There is no compatibility shim in a versioned formula scheme.

The fourth is the scope of the tap. It packages extensions and nothing else: no PHP version management, no ini file management, no per-site configuration. Those belong to the php tap and to your own php.ini, and a team that expects the extension tap to configure them will be disappointed.

The fifth is the trust decision. Marking a tap as trusted is a permanent, machine-wide statement about a third-party repository of build scripts. The maintainer is a well known figure in the PHP tooling world and the formulae are open source under MIT, but the trust step is the kind of thing a security policy should mention.

How it compares with pecl, with the homebrew/core PHP and with static builds

The comparison with pecl is the direct one, and the difference in approach is packaging versus compilation. pecl install xdebug downloads the source, compiles it against your PHP headers, and drops a shared object into your extension directory. It works with any PHP you have installed, including a system package's, and it has no opinion about which interpreter is on your PATH. What it lacks is versioning, since pecl tracks the extension's own releases rather than the PHP version, so a system with two PHP versions ends up with one extension that fits only one of them.

Homebrew's own core tap is the other comparison. It has PHP and a limited set of extensions, and it is the mainstream choice, but its formulae are built for one PHP version at a time, and the version matrix a developer with several interpreters needs is not something core provides. This tap exists precisely in that gap and coordinates with the author's PHP tap.

Static builds are the third approach and they solve a different problem. A tool such as static-php-cli or a container image with extensions compiled in produces a self-contained binary with no shared objects and no ini files, which is excellent for deployment and CI reproducibility. The cost is that you assemble the extension set yourself, so you get exactly what you asked for rather than what a tap has packaged.

So the choice is between convenience and control of the interpreter you are running. A developer who wants a working extension now, and who has the extension versions under Homebrew's control, will find the tap the fastest route. A team that needs reproducible, self-contained artefacts will build its own.

Editorial conclusion

This tap suits a developer on macOS or Linux who wants a specific PHP extension installed the way every other tool on the machine is installed, and who is managing more than one PHP version at a time, since the per-version formulae are the reason to prefer it over a manual pecl install. It is the wrong tool for a system package manager, since a tap is Homebrew only, and the wrong choice for macOS on Intel, which the README says is not supported. Before installing, confirm the PHP version you need is the one linked, because a formula is built against a specific interpreter, and remember to restart php-fpm after the change, since an extension that is installed but not loaded is the most common way for this to look broken.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. shivammathur/homebrew-extensions on GitHub