Installing PECL and PEAR on macOS El Capitan, Sierra, and Early High Sierra
The release of OS X 10.11 El Capitan introduced System Integrity Protection (SIP), a security feature designed to lock down critical system directories like /usr and /bin. While this enhancement significantly hardened the operating system against unauthorized modifications, it inadvertently broke standard installation workflows for legacy PHP extensions. Specifically, the commands pear install and pecl install attempted to drop files directly into protected paths, triggering permission denials before any actual compilation occurred.
On El Capitan, disabling SIP entirely is a viable option but generally discouraged due to the security risks it reintroduces. A more pragmatic approach involves installing the necessary tools in a user-owned directory that remains outside SIP's reach. The standard location for this is $HOME/local. By prefixing your phpize and compiler flags with paths under your home directory, you can bypass the lockdown without compromising system integrity.
To set up a functional environment on El Capitan or early versions of Sierra (10.12) and High Sierra (prior to 10.13.3), you must first ensure that Homebrew is installed. While macOS comes with PHP pre-installed, the version included in the base system often lacks modern extensions found in PECL repositories. You should verify your current setup by running php -i to check available modules and the configured phpize path.
The core of the workaround relies on creating a local build directory. Create a folder named local inside your home directory:
mkdir ~/local
Next, you need to install the PHP development tools required for compiling extensions. Using Homebrew is the most reliable method to acquire these dependencies without conflicting with system files. Run the following command to install the necessary compiler and libraries:
brew install libtool bison flex wget unzip curl
Once the dependencies are in place, you must configure the PHP build environment. The critical step is defining the build_dir variable for your user's PHP installation. You can do this by editing your shell profile (.zshrc or .bash_profile) and adding an alias or function that sets the environment variables before invoking pecl or pear.
However, a more direct method involves modifying the phpize command itself or ensuring that the PEAR_ROOT_DIR is set to a writable location. If you are using Homebrew to manage your PHP version (e.g., via brew install php56 or similar), the installation paths will likely be under /usr/local. You must check if these locations are protected by SIP.
If the system PHP is in /usr/bin/php, it is highly probable that writing to /usr/local/lib/php/extensions/ will fail on El Capitan. The solution is to install PECL extensions into a custom directory within your home folder. You can achieve this by setting the PHP_PECL_EXTENSION_DIR environment variable or by creating a symlink, though symlinks are often blocked by SIP.
A robust strategy involves installing PHP entirely from Homebrew and managing extensions locally. When you run pecl install <extension>, it typically asks for a destination directory. You can explicitly specify a path under $HOME/local/lib/php/extensions/ during the installation process. This ensures that the compiled shared object (.so file) lands in a location where your user has write permissions, bypassing the SIP restrictions on /usr.
For example, if you are installing the redis extension, you might need to adjust the build flags or use a specific installation path provided by Homebrew's PHP formula. If you are using a system-installed PHP that you cannot replace, your only viable route is to ensure all compilation happens in $HOME/local. This requires manually setting the build_dir and ensuring the include paths point to your local library headers.
It is important to note that this workaround adds complexity to your development environment. You will need to manage two sets of dependencies: one for system PHP (if used) and one for your local setup. Additionally, scripts that depend on specific extension versions loaded from /usr/local/lib might break if you switch between the system PHP and a Homebrew-managed PHP without careful path management.
Before proceeding with any installation, verify that SIP is active by running csrutil status. If it returns "enabled," you must rely on user-owned directories for all third-party extensions. The trade-off here is increased setup time but maintained security posture. Once configured, your local environment will be isolated from system changes, allowing you to install experimental or legacy PECL modules that are no longer supported by Apple's core distributions.
If you encounter issues with pear specifically, remember that PEAR stores package data and dependencies in its own root directory, which is often /usr/local/Cellar/php/... or similar. You may need to adjust the PEAR_ROOT_DIR environment variable to point to a custom location like $HOME/local/pear. This ensures that PEAR's metadata and downloaded packages do not attempt to write to protected system directories.
By carefully configuring your build paths and utilizing Homebrew to manage dependencies, you can maintain a functional PHP development environment on these older macOS versions without disabling System Integrity Protection. This approach respects the security model introduced in El Capitan while providing the flexibility needed for legacy extension support.