macOS Homebrew PHP-FPM Setup Guide

This guide documents the required steps after installing a new PHP version using Homebrew, especially when using PHP-FPM with custom ports.

1. Install PHP Version

Install the desired PHP version:

brew install [email protected]

Replace 8.4 with your required version:

brew install [email protected]
brew install [email protected]
brew install [email protected]

2. Locate the PHP-FPM Pool Config

Homebrew PHP-FPM pool configuration is usually located at:

/opt/homebrew/etc/php/8.4/php-fpm.d/www.conf

For Intel-based Macs, it may be:

/usr/local/etc/php/8.4/php-fpm.d/www.conf

For Apple Silicon Macs, use:

/opt/homebrew/etc/php/{version}/php-fpm.d/www.conf

Example for PHP 8.4:

nano /opt/homebrew/etc/php/8.4/php-fpm.d/www.conf

3. Update www.conf Listen Port

Find the listen directive:

listen = 127.0.0.1:9000

Change it to your desired port. Recommended port convention — the version number maps to the port:

Example:

; PHP 8.4
listen = 127.0.0.1:9084

Avoid using only the port number (listen = 9084) — always bind the address explicitly:

listen = 127.0.0.1:9084

4. Validate PHP-FPM Configuration

Before restarting the service, validate the PHP-FPM config:

/opt/homebrew/opt/[email protected]/sbin/php-fpm -tt

Replace 8.4 with your installed version. If validation fails, fix the reported config issue first.

5. Restart PHP-FPM Service

Restart the specific PHP version:

brew services restart [email protected]

6. Confirm PHP-FPM Is Running

Check Homebrew services:

brew services list | grep php

Check if the configured port is listening:

lsof -nP -iTCP:9084 -sTCP:LISTEN

Expected output should show php-fpm listening on the selected port:

php-fpm  1234  jerwin  9u  IPv4  TCP 127.0.0.1:9084 (LISTEN)

7. Update Nginx or Local Site Config

If your local site uses Nginx, update the FastCGI PHP-FPM port:

location ~ \.php$ {
    fastcgi_pass 127.0.0.1:9084;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

After editing the Nginx config, reload Nginx:

brew services restart nginx

Or:

nginx -s reload

8. Troubleshooting

Check which PHP-FPM process owns a port:

sudo lsof -nP -iTCP -sTCP:LISTEN | grep php-fpm

Check a specific port:

lsof -nP -iTCP:9084 -sTCP:LISTEN

Search all PHP-FPM listen configs:

grep -R "^[[:space:]]*listen[[:space:]]*=" /opt/homebrew/etc/php/*/php-fpm.d 2>/dev/null

Check PHP-FPM logs:

tail -n 100 /opt/homebrew/var/log/php-fpm.log

Or find them:

find /opt/homebrew/var/log -iname "*php*" -type f

If multiple PHP-FPM versions are running and causing confusion, stop the ones you do not need:

brew services stop [email protected]
brew services stop [email protected]
brew services stop [email protected]

Then restart the required version:

brew services restart [email protected]

9. Quick Checklist

After installing a new PHP version:

brew install [email protected]
nano /opt/homebrew/etc/php/8.4/php-fpm.d/www.conf

Update:

listen = 127.0.0.1:9084

Validate:

/opt/homebrew/opt/[email protected]/sbin/php-fpm -tt

Restart:

brew services restart [email protected]

Verify:

lsof -nP -iTCP:9084 -sTCP:LISTEN

Update Nginx:

fastcgi_pass 127.0.0.1:9084;

Restart Nginx:

brew services restart nginx