Configuring Apache to Use Homebrew-Installed PHP on macOS: Resolving Module Compatibility Issues

Problem Background and Diagnosis

In macOS development environments, developers often encounter situations where PHP extensions installed via Homebrew (e.g., mcrypt) are not properly loaded by the Apache server. This typically occurs due to path conflicts between the system's built-in PHP version and the Homebrew-installed PHP version. To diagnose this issue, first confirm the PHP version currently used by Apache. This can be checked by executing the following command in the terminal:

php -v

This command displays the PHP version used in the command line. However, Apache may use a different PHP binary. To verify the actual PHP module loaded by Apache, inspect the Apache configuration file httpd.conf. This file is usually located at /etc/apache2/httpd.conf. Open it with a text editor (e.g., nano or vim) and search for lines containing LoadModule php. For example:

LoadModule php5_module /usr/libexec/apache2/libphp5.so

If the path points to a system directory (e.g., /usr/libexec/), Apache is using the macOS built-in PHP version. In contrast, Homebrew-installed PHP modules are typically located in directories like /usr/local/opt/ or /usr/local/Cellar/. This path discrepancy is the root cause of extensions (e.g., mcrypt) not appearing in phpinfo().

Configuring Apache to Use Homebrew-Installed PHP

To resolve this issue, modify the Apache configuration file to load the Homebrew-installed PHP module. First, determine the exact path of the Homebrew-installed PHP module. Use the brew info command to obtain detailed information. For example, for PHP version 7.4:

brew info php@7.4

The command output will include path information similar to the following:

To enable PHP in Apache add the following to httpd.conf and restart Apache:
    LoadModule php_module /usr/local/opt/php@7.4/lib/httpd/modules/libphp.so

Next, edit the httpd.conf file. Locate the existing LoadModule php line and either comment it out or replace it with the above path. For example:

# LoadModule php5_module /usr/libexec/apache2/libphp5.so  # Comment out the system version
LoadModule php_module /usr/local/opt/php@7.4/lib/httpd/modules/libphp.so  # Use the Homebrew version

Additionally, ensure the configuration file includes directives for handling PHP files. Add or modify the following section in httpd.conf:

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Also, check that the DirectoryIndex directive includes index.php to ensure Apache correctly recognizes PHP index files:

DirectoryIndex index.php index.html

After making these changes, save the file and restart the Apache service to apply the modifications:

sudo apachectl restart

Once restarted, verify the configuration by creating a simple PHP info page (e.g., phpinfo.php). Create this file in the web root directory (typically /Library/WebServer/Documents/) with the content <?php phpinfo(); ?>, then access it in a browser. If the page displays the PHP version matching the Homebrew installation and lists extensions like mcrypt, the configuration is successful.

Advanced Configuration and Management Tips

For developers managing multiple PHP versions, Homebrew offers flexible solutions. First, use brew search php to view available PHP versions, with installed versions marked by a checkmark. Install a specific version (e.g., PHP 5.6) with the command:

brew install php@5.6

To easily switch between different versions in the command line, add aliases to the shell configuration file (e.g., ~/.zshrc or ~/.bashrc). For example:

alias php@5.6='$(brew --prefix php@5.6)/bin/php'
alias php@7.0='$(brew --prefix php@7.0)/bin/php'

This allows quick checks of specific PHP versions with commands like php@5.6 -v. For developers using Composer or Laravel Artisan, create corresponding aliases to ensure tools use the correct PHP version. For example:

alias composer@5.6='php@5.6 $(which composer)'
alias artisan@5.6='php@5.6 artisan'

Furthermore, ensure the PATH environment variable prioritizes Homebrew's PHP binaries to avoid version inconsistencies between the command line and web server. Add the following to ~/.zshrc:

export PATH="/usr/local/opt/php@7.4/bin:$PATH"

Then execute source ~/.zshrc to apply the changes immediately. This configuration approach not only resolves Apache extension loading issues but also enhances the maintainability and consistency of the development environment.

Common Issues and Troubleshooting

During configuration, several common issues may arise. If Apache fails to restart, first check for syntax errors in httpd.conf. Validate the configuration file with the command:

sudo apachectl configtest

If the output shows Syntax OK, the configuration file is correct; otherwise, correct errors based on the message. Another common issue is insufficient permissions. Ensure write permissions for the httpd.conf file, using sudo for editing if necessary. If the PHP module path is incorrect, rerun brew info php@version to confirm the path, noting that module filenames may differ between PHP versions (e.g., libphp5.so for 5.x vs. libphp.so for 7.x).

For extension loading problems, beyond modifying Apache configuration, also check the PHP configuration file php.ini. Homebrew-installed PHP configuration files are typically located in /usr/local/etc/php/version/. Ensure required extensions (e.g., extension=mcrypt.so) are enabled in php.ini. If issues persist, try reinstalling the extension:

brew reinstall php@7.4

Finally, keeping Homebrew and PHP versions updated is key to avoiding compatibility problems. Regularly run brew update and brew upgrade, and refer to official documentation (e.g., the Homebrew PHP formula page) for the latest configuration guidelines.