Skip to content
Butler

PHP versions

Butler can run several PHP versions side by side. You set one as the global default and override it per project whenever you need to.

Set the global default

Section titled “Set the global default”
Terminal window
butler use 8.3

Every site that hasn’t pinned its own version uses this one. You can also set the global version from the PHP section of the menu bar app.

Install another version

Section titled “Install another version”

If a version isn’t installed yet, add it:

Terminal window
butler install php@8.4

Installed versions appear in the app’s PHP section, where you can switch the default or install more with a click.

Pin a version to one site

Section titled “Pin a version to one site”

To run a single project on a different PHP version without changing your global default, run butler isolate from the project directory:

Terminal window
cd ~/Sites/my-app
butler isolate 8.2

Or target a site by name with --site from anywhere:

Terminal window
butler isolate 8.2 --site my-app

Now my-app.test uses PHP 8.2 while everything else stays on the default. Undo it with butler unisolate (also auto-detects from the current directory, or takes a site name):

Terminal window
butler unisolate my-app

You can also pin the version in the project’s butler.yml, which is handy because it travels with the repo:

php: "8.2"

Run PHP and Composer

Section titled “Run PHP and Composer”

butler php runs the active PHP for the current directory — the isolated version if the folder is a site with one pinned, otherwise your global default:

Terminal window
butler php -v
butler php artisan migrate

butler composer runs Composer through that same PHP, so your dependencies are resolved against the version the site actually uses:

Terminal window
butler composer install
butler composer require laravel/pint --dev

This means you don’t have to juggle a system PHP or remember which version is on your PATH — Butler always uses the right one for where you are.

Tuning php.ini

Section titled “Tuning php.ini”

Butler ships each PHP version with an ini tuned for real frameworks (sensible memory limits, OPcache settings and so on). If you’ve edited a version’s php.ini and want to get back to Butler’s defaults, reset it from the PHP section of the app. Per-site PHP settings can also be set in butler.yml:

server:
  phpSettings:
    memory_limit: "1G"