brew-php-switcher: one command to repoint Apache and the CLI at another PHP

The problem it solves, in one command

Brew PHP switcher is a simple script to switch your Apache and CLI configs quickly between major versions of PHP.

The situation it addresses is described plainly. If you support multiple products and projects built using either brand new or old legacy PHP functionality, and you find it a pain to change config files continually, this makes the whole process one command. That is a small problem with an unglamorous solution, and the whole repository is a single shell script, phpswitch.sh, alongside the README, a LICENSE and a _config.yml.

The scope is narrower than the name suggests in one way and wider in another. Narrower because it only handles Apache and the CLI, and it only works for macOS with PHP installed through Homebrew. Wider because Valet is also handled, and Valet is the other piece of the macOS PHP setup that usually needs changing when you move between versions.

The mechanism is a text substitution in the Apache config. The script needs the native macOS PHP module to be commented out first:

#LoadModule php5_module libexec/apache2/libphp5.so

And then Brew PHP Switcher automatically adds the Homebrew PHP module location in the Apache config, in the format:

#LoadModule php5_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp5.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp7.so
#LoadModule php7_module /usr/local/opt/[email protected]/lib/httpd/modules/libphp8.so

So the transformation is to comment out every Homebrew PHP module line and uncomment the one for the version you asked for. That is the entire trick, and it is why the script needs the native module line to be commented in the first place, so that there is exactly one active PHP module at the end.

The flags, and what skipping a config means

The command takes a version and then a set of options that control which configuration files get touched.

The -s flag skips the Apache and Valet config switch, and it takes an optional value naming which one to skip:

# skip apache only
brew-php-switcher 5.6 -s

# skip valet only
brew-php-switcher 5.6 -s=valet

# skip valet & apache
brew-php-switcher 5.6 -s=valet,apache

The -c flag does the opposite, switching a specific config rather than skipping one:

# switch valet config only
brew-php-switcher 5.6 -c=valet

# switch valet & apache config only
brew-php-switcher 5.6 -c=valet,apache

# switch apache config only
brew-php-switcher 5.6 -c=apache

The two flags are mirror images and they are not redundant, because the default is to switch both. If you only care about the CLI, -s alone means touch nothing. If you want Apache but not Valet, -c=apache does that. The reason both exist is that Valet and Apache are often in different states on the same machine, and a developer who only ever serves through Valet has no reason to have an Apache config rewritten on every switch.

There is one behavioural note about the default. When you run the command with no flags, it will switch the Apache config, and the README marks that with a note. Since the script is otherwise silent about what it edits, that note is the only warning that a config file is about to be rewritten, so it is worth knowing before you run it the first time.

The version lists in this README disagree, and that matters

Here is the detail that would catch someone out, and it is visible in the documentation itself rather than buried in an issue.

The caveats section says the tool is for users of OSX only who have installed PHP via Homebrew, and for PHP version 5.6, 7.0, 7.1, 7.2, 7.3, 7.4 and 8.0 only. The example of the Apache module lines it writes also covers that same set, from [email protected] through [email protected], and the module name changes from php5_module to php7_module at 7.0 because the Apache module binary was renamed between those major versions.

The installation section, however, says that where 5.6 exists you should replace it with the syntax of 5.6, 7.0, 7.1, 7.2, 7.3, 7.4, 8.0, 8.1, 8.2, 8.3, 8.4 or 8.5 depending on which version is required, and the example it gives is:

brew-php-switcher 5.6

So the caveats list stops at 8.0 while the installation section lists up to 8.5. The script itself is a shell script, so it is worth opening phpswitch.sh and checking the version list it actually implements before you rely on a version above 8.0.

There is a second inconsistency in the same file. The Version section states 2.3, while the tagged releases are v2.6 from 2024-11-30, v2.5 from 2023-11-30 and v2.4 from 2021-12-07. The README's version line is stale, so the release list is the more reliable indicator of what is published.

Neither of these is a blocker, but both are reasons to read the script rather than the documentation when you are switching to a version the caveats do not list.

One script, one file, and what the repository holds

The repository is about as small as a useful project gets, and the file listing says the same thing. At the top level there is phpswitch.sh, which is the tool, a README.md, a LICENSE, a .gitignore and a .github directory, plus a _config.yml.

That _config.yml is worth a note because it is not a Jekyll site file. The filename is the GitHub Pages convention, and a README.md with a _config.yml beside it is the standard way to have a repository's README rendered with a theme when it is viewed on GitHub. The theme affects how the README looks on the site, not how the script behaves.

The single script is the whole implementation, which means there is no library to depend on and no framework to learn. If you want to understand exactly what it does to your machine, you read one file, and if you want to change the behaviour you edit one file. For a tool that rewrites configuration files in your Apache directory, that is a genuine advantage over an equivalent that arrived as a package with a dependency tree.

The .github directory holds the CI workflow, and the badge in the README links to the ci.yml workflow on the master branch, so the script is tested in continuous integration even though the project itself is a single file. The LICENSE is MIT, the repository is not archived, and the last push was on 2026-07-15, with the last tagged release being v2.6 on 2024-11-30.

One thing you will not find in the repository is an installation method other than Homebrew. The install command is brew install brew-php-switcher, so the tool is distributed the same way as the PHP versions it switches between, which is convenient but also means the only supported platform is the one Homebrew targets for your machine.

What this script is and is not for

The first limitation is the platform, and it is absolute. This is macOS only, and only for PHP installed through Homebrew. There is no Linux path, no Docker path, and no support for a PHP that came from a package manager other than Homebrew, because the whole mechanism depends on the Homebrew install prefix layout at /usr/local/opt/[email protected].

That prefix is also why the script is dated in one respect. The module paths it writes are /usr/local/opt/[email protected]/lib/httpd/modules/libphp5.so and similar, which is the Intel Homebrew layout. Apple Silicon Homebrew installs to /opt/homebrew, so the paths differ, and the script would need to derive them rather than hard-code them.

The second limitation is what it does not manage. The script rewrites the Apache module line and the Valet configuration. It does not install or uninstall PHP versions, so brew install [email protected] is still your job. It does not restart Apache or reload Valet, so you still need to do that yourself for the change to take effect. And it does not touch your php.ini files, so a version-specific configuration in your home directory still has to be managed separately.

The third limitation is the assumption that one PHP version is active for the whole machine. The script edits global configuration files, not per-project ones. For a developer with several projects each wanting a different PHP version simultaneously, the answer is a per-project setup such as per-directory Valet configuration, and this script is the wrong tool for it.

The project itself is a single file, so there is not much more to it than what the README says. It is MIT licensed, the repository is not archived, the last push was on 2026-07-15, and there is a CI workflow for the repository.

Editorial conclusion

brew-php-switcher suits a macOS developer who juggles several PHP major versions across projects and wants to change both the web server and the CLI in one step, rather than editing the Apache config by hand. It is a poor fit for anything but Homebrew installations on macOS, and a poor fit if you rely on Valet or on a PHP version outside the listed set. Before adopting, read the caveats section rather than the options list, because the Apache config must already have the native macOS PHP module commented out, and check which PHP versions your own projects need, since the caveats and the installation section list different version ranges.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. philcook/brew-php-switcher on GitHub
4. README
5. Releases