How to Setup PIE for PHP Extensions on macOS

Lately, I found myself navigating the usual PECL setup hurdles. The hardest part is that PECL is deprecated, and that’s how I rediscovered Pie and it turns out to be a much more straightforward way to install PHP extensions.

Pie is the official PHP extension installer. Credits to The PHP Foundation.

What is PHP Pie?

Pie is a new tool for installing PHP extensions. It is a replacement for PECL, and it is designed to be faster and more reliable than PECL.

Prerequisites

• Componets of the GNU build system: autoconf, automake, libtool, m4, make, gcc
• PHP8.1 or newer
• PHP extensions: phpize, zip
• Git

We can install core components of the GNU build system using Homebrew with the following command:

brew install git autoconf automake libtool m4 make gcc

Some of these components might have been installed on your machine, the installation command will update them to latest versions.

Laravel Herd Workaround for phpize Extension

PHP binaries from Laravel Herd does not include phpize extension, but we include it by installing PHP via hombrew.

If you've installed PHP via homebrew you can skip this part

brew install php

Now let's run the command below to confirm if zip extension is enabled in our PHP configuration:

php -m

Installing Pie via CLI

Now that we have met the prerequisites, we can install Pie on macOS using the command below:

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

We can confirm that Pie is installed by running the command below:

pie --version

GitHub verification (optional)

We can verify the signature of the downloaded pie.phar file, but first we need the GitHub CLI installed on our machine.

Let's install GitHub CLI using Homebrew:

brew install gh

Now we can verify the signature of the downloaded pie.phar file using the gh attestation verify command:

curl -fL --output /tmp/pie.phar https://github.com/php/pie/releases/latest/download/pie.phar \
  && gh attestation verify --owner php /tmp/pie.phar \
  && sudo mv /tmp/pie.phar /usr/local/bin/pie \
  && sudo chmod +x /usr/local/bin/pie

Installing Pie via executable

We can also install Pie via executable, but it is still experimental and most importantly, doesn't have the pie self-update feature enabled. Download the executable from the Pie GitHub page.

How to install PHP extensions using Pie

Now we can download, build, and install an extension using the pie install <vendor>/<package> command. For example, to install the MongoDB PHP extension, we will run the command below:

pie install mongodb/mongodb-extension

Manually load built extension

We can manually load a built extension into Herd PHP configuration by adding the absolute path to the extension.so file to our php.ini configuration file like this:

# Absolute path to the extension.so file
extension=/path/to/mongodb/mongodb.so

Note: This is only necessary if you are using PHP binaries from Laravel Herd due to readonly error when Pie tries to automatically install a built extension.

Below, I have included examples for installing some popular PHP extensions in the community.

Installing MongoDB PHP extension

MongoDB driver extension.

pie install mongodb/mongodb-extension

Installing xDebug PHP extension

Xdebug is a debugging and productivity extension for PHP.

pie install xdebug/xdebug

Installing Swoole PHP extension

Swoole is an event-driven, asynchronous, coroutine-based concurrency library with high performance for PHP.

pie install swoole/swoole

Installing PhpRedis extension

A PHP extension for Redis.

pie install phpredis/phpredis

Installing Imagick extension

The Imagick PHP extension.

pie install imagick/imagick

A list of Pie compatible extensions can be found on Packagist.

That's all for now, I hope this article has been helpful to you. If you have any questions or suggestions, please feel free to send me a DM via X or LinkedIn.