Adding PHP extensions to System PHP under OS X 10.15 (Catalina)

Adding PHP extensions to System PHP under OS X 10.15 (Catalina)

Sunset over Catalina Island

Photo by Don Graham and used under Creative Common 2.0 Attribution-ShareAlike license.

Taking a break from development for a day or two and upgrading my laptop to Catalina seemed like a good way to kick off the new year.

Catalina upgrades the System PHP version from 7.2.x to 7.3.9, which is a change I am eager to get as PHP 7.2 is no longer actively supported by the PHP developer community. The OS X upgrade process always includes a few surprises for developers, however.

A big surprise in this upgrade was that Catalina improves security by adding a read-only file system for critical system files you don't want tampered with. That makes a lot of sense, but it also complicates using PECL or phpize, because the paths under /usr that they references are read-only now.

After the upgrade my dev sites were by-and-large working well, but on one site I ran into the following error:

Error: Class 'ZipArchive' not found

It turns out that the PHP 7.3 that ships with Catalina does not include the zip/ZipArchive support. This project requires ZipArchive, so either I could switch to a different method of installing PHP, like using brew or a Docker or Lando environment, or I could figure out how to reenable zip support in the system PHP.

I went with the latter approach.

Personally, I love Lando for secondary PHP versions but I find the performance penalty running Docker on a Mac too high to use it for my primary environment. This project, for example requires frequent site rebuilds, which make the efficiency gains from making that a 10 minute process rather than close to an hour critical to my productivity.

A lot of the developers at Affinity Bridge use brew to run multiple PHP versions on their laptops. I've used that approach too but have experienced headaches managing dependencies that way, with what is intended to be a small change to my AMP stack triggering updates of seemingly unrelated tools like python3 that cause breakage elsewhere in my environment. So if I can avoid this approach, I do.

I gleaned information from a number of other developers who've run into similar problems and I came up with a solution.

Step 1: Install PEAR/PECL support

cd /tmp
curl -s -O
sudo php install-pear-nozlib.phar -d /usr/local/lib/php -b /usr/local/bin 

Step 2: Download zip extension source

I tried installing zip with pecl, but that failed because the PHP header files were missing. So I downloaded the source for the zip extension from pecl.

pecl download
tar -xzvf zip 

Step 3: Download PHP src/header files

To build PHP extensions, you need the header files for the version of PHP you are targetting. On OS X this is done with XCode (credit).

 xcode-select --install 
To verify that the header files are available now and find their path:
$ sudo find /Library -name php.h

Step 4: Copy/modify phpsize and php-config

In order to make phpize and php-config find the PHP header files in the location that XCode places them rather than in /usr/include/php -- a read-only location now -- I followed some tips I found elsewhere and copied and modified phpize and php-config to change the include directory in each of them.

cp /usr/bin/phpize /usr/local/bin/phpize 
cp /usr/bin/php-config /usr/local/bin/php-config 

Then I edited the include path in each of them. Here are the diffs:

 local:/tmp/zip-1.15.5/modules $ diff /usr/bin/phpize /usr/local/bin/phpize
< includedir="`eval echo ${prefix}/include`/php"
> includedir="`eval echo /Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk/usr/include`/php"
local:/tmp/zip-1.15.5/modules $ diff /usr/bin/php-config /usr/local/bin/php-config
< include_dir="${prefix}/include/php"
> include_dir="/Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk/usr/include/php" 

Step 5: Build the zip PHP extension

With all of those changes in place, I could now build the zip extension.

cd zip-1.15.5
 ./configure -with-php-config=/usr/local/bin/php-config 

Step 6: Install zip PHP extension

make install fails to install the extension, again because of the read-only file system. So instead I created an extension directory under /usr/local/php.

mkdir -p /usr/local/php/extensions 
cp modules/ /usr/local/php/extensions/ 

Step 7: Update your PHP.ini

Finally we need to tell PHP to load this extension.

 sudo vim /etc/php.ini 
Add the following line:
Restart apache with sudo apachectl restart and you'll see the zip extension being loaded now.

Zip extension

I expect the PHP and Mac development community will work out the issues with the read-only filesystem causing make and PECL install to fail, but knowing how to compile your own PHP extensions and use them with the system PHP on OS X is super useful. Presumably this process could be used for other useful PHP extensions like xdebug.

Happy coding!