Yosemite / El Capitan php-gd + mcrypt installation
Running PHP on macOS Yosemite or El Capitan often reveals a fragmented environment where Apple's system build handles basic needs but leaves out critical extensions required for modern web applications. Specifically, you might find that while the GD library is present, it lacks PNG support, and the Mcrypt extension might be entirely absent. This guide addresses how to verify these states and install the missing components using Homebrew on PHP 5.5.x builds.
Diagnosing Missing Modules
Before attempting any installation, you must establish exactly what your runtime environment provides. Execute the following command in your terminal:
$ php -m
This output lists all compiled-in modules. If you are missing specific functionality, look for the absence of gd (specifically regarding PNG) or mcrypt. The standard advice from community resources suggests checking accepted Stack Overflow answers for general Homebrew troubleshooting if you encounter obscure errors during this phase.
Enabling Full GD Support with PNG
Apple's default PHP build on OS X often includes the GD library but strips out image format handlers like PNG to reduce binary size or due to licensing constraints in older system versions. If your application relies on image manipulation, you will likely hit a hard stop if imagecreatefrompng() is undefined.
This results in a fatal error that halts script execution:
Call to undefined function imagecreatefrompng()
To resolve this, you need the "full" GD module which includes PNG support. While Apple provides a basic build, switching to a Homebrew-managed PHP version ensures all dependencies are resolved correctly. You can install the necessary package using Homebrew:
$ brew install php55-gd
After installation, ensure that your shell is configured to use this new PHP binary instead of the system one, or verify that the homebrew PHP is prioritized in your PATH.
Installing Mcrypt
The Mcrypt extension was deprecated and removed from newer PHP versions due to security vulnerabilities and the availability of more secure alternatives like OpenSSL. However, if you are maintaining legacy codebases on Yosemite or El Capitan that rely on Mcrypt (such as older Laravel versions), you must install it explicitly.
Homebrew does not include Mcrypt in its standard PHP formulas. You must install the extension package separately. Follow these steps:
- Search for available packages: Confirm the specific formula name matches your target PHP version.
$ brew search mcrypt - Install the specific extension: Use the versioned formula to match your PHP 5.5.x setup.
$ brew install php55-mcrypt - Verify the installation: Run the module list again to confirm
mcryptappears in the output.$ php -m | grep mcrypt
If you previously installed a PHP version without Mcrypt and now need it, simply reinstalling the extension usually suffices, provided your Homebrew PHP manager (like homebrew-php or similar) handles the symlink updates automatically.
Managing Multiple PHP Versions
A common pitfall in OS X development is mixing system PHP with Homebrew PHP. The system version often lacks the extensions you just installed, while your script path might still point to /usr/bin/php.
To seamlessly switch between different PHP versions (for example, toggling between a clean system build and a Homebrew build with all extensions), consider using a dedicated utility like brew-php-switcher. This tool manages the symbolic links in your $PATH, allowing you to quickly swap active versions without manually editing configuration files. This is particularly useful if you are working on projects that require different PHP runtimes or if you need to test against both old and new PHP versions simultaneously.
By explicitly installing these extensions, you ensure your application has access to the necessary image processing and cryptographic functions required by legacy frameworks.