Adding PHP extensions to System PHP under OS X 10.15

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 https://pear.php.net/install-pear-nozlib.phar
sudo php install-pear-nozlib.phar -d /usr/local/lib/php -b /usr/local/bin 

(credit)

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 https://pecl.php.net/get/zip
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
/Library/Developer/CommandLineTools/SDKs/MacOSX10.14.sdk/usr/include/php/main/php.h
/Library/Developer/CommandLineTools/SDKs/MacOSX10.15.sdk/usr/include/php/main/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
8c8
< 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
9c9
< 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
phpize
 ./configure -with-php-config=/usr/local/bin/php-config 
make 

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/zip.so /usr/local/php/extensions/zip.so 

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:

 extension=/usr/local/php/extensions/zip.so 

Restart apache with sudo apachectl restart and you'll see the zip extension being loaded now.