Switch of PHP versions not working on Mac
When managing a local development environment on macOS, switching between PHP versions is a routine task that often trips up developers due to how system paths and shell aliases are resolved. The core issue usually stems from a misunderstanding of the order in which your terminal checks for executables. In your specific scenario, you have High Sierra installed with an initial PHP 7.1, upgraded to 7.2, and attempted to move to 7.3 using Homebrew. Despite running brew unlink php@7.2, installing 7.3 as a service, and linking it, the php -v command still reports version 7.2.25.
This behavior is not a failure of Homebrew's package manager logic but rather a precedence issue in your shell environment. When you execute php -v, your system searches for the executable in directories listed in the $PATH environment variable, starting from the leftmost entry. If the old PHP 7.2 binary remains in a directory that appears earlier than the new Homebrew PHP 7.3 installation (typically located at /usr/local/bin or /opt/homebrew/bin), your shell will invoke the older version regardless of what brew link suggests.
The command brew unlink php@7.2 effectively removes the symlink pointing to PHP 7.2 within Homebrew's managed directories, but it does not necessarily remove the actual binary files from your system path if they were installed globally or if other mechanisms are pulling them in. Furthermore, brew services install php@7.3 starts the PHP daemon (if you use it as a web server), but it does not automatically update the CLI executable that php -v calls. The linking step brew link php@7.3 is critical, but if /usr/bin/php or another system directory takes precedence over /usr/local/bin/php, the switch will appear to fail.
To diagnose and resolve this, you must inspect which binary is actually being executed. Run the following command in your terminal:
which php
php -v
ls -l $(which php)
The which command shows the full path of the executable currently found first in your $PATH. The ls -l output will reveal whether the binary is a real file or a symlink, and crucially, which directory it resides in. If you see a path like /usr/bin/php, that is likely the system-default PHP from your macOS installation (or an older version installed globally), not the Homebrew-managed one.
To successfully switch to PHP 7.3, you need to ensure that the Homebrew binary for PHP 7.3 is the first match in your $PATH. You can achieve this by modifying your shell configuration file (such as ~/.bash_profile, ~/.zshrc, or ~/.fishrc) to prepend the Homebrew bin directory to your path. Add the following line before any other path manipulations:
export PATH="/usr/local/bin:$PATH"
# Or for Apple Silicon Macs with Homebrew on ARM64:
# export PATH="/opt/homebrew/bin:$PATH"
After updating your configuration file, restart your terminal or run source ~/.zshrc to apply the changes. Once the path is updated, verify again with php -v. You should now see version 7.3.x.
If you prefer not to modify global paths, another robust approach is to use aliases. Add this to your shell config:
alias php='/usr/local/bin/php'
# Or adjust the path based on your specific Homebrew installation location
This method ensures that whenever you type php, it explicitly calls the correct binary without relying on global path ordering. However, be aware that aliases only affect the current shell session unless properly sourced in your config file.
One common pitfall when using Homebrew PHP versions is mixing CLI and server modes. If you are developing a Laravel or Symfony application, ensure that both your CLI tools and your web server (like php-fpm running via Nginx/Apache) are pointing to the same PHP version. Inconsistencies here can lead to confusing errors where code runs fine in one environment but fails in another due to extension mismatches or framework compatibility issues.
For those working specifically with Laravel projects, it is often helpful to use a dedicated tool like laravel-upgrade or rely on Docker containers if you need to isolate environments completely. While Homebrew is excellent for native macOS development, keeping your PHP versions isolated via Docker (docker run -it php:7.3-cli) can prevent these path conflicts entirely, allowing you to switch versions instantly by changing the container tag without touching your host system's configuration.
Finally, if you continue to experience issues after verifying the path, check for any global .php files or scripts that might be overriding the version. Sometimes, legacy installers leave behind wrappers in /usr/local/bin or /usr/bin. Use brew cleanup to remove orphaned files and ensure a clean state before re-linking PHP 7.3.