PHP

Every site runs on FrankenPHP's PHP: one current version, shared by all your sites. On macOS you can pin a site to an older version when it needs one.

Which PHP#

FrankenPHP is Caddy, the web server, with PHP built in. It serves your sites, and the same PHP runs WP-CLI, artisan and Composer when you use cove wp, cove artisan and cove composer, so a command and the site it works on always agree.

cove php                       # every site's PHP, and the default
cove php mysite                # one site's

On macOS, Cove installs FrankenPHP from its GitHub release, with PHP and its extensions compiled in. On Linux it comes from FrankenPHP's package repository, and Cove adds the extension packages WordPress and Laravel need. Either way you have the MySQL, PostgreSQL and SQLite drivers, Redis, GD, intl, mbstring, zip, curl and bcmath. To see the full list:

frankenphp php-cli -m

cove upgrade brings FrankenPHP up to its latest release, and PHP with it.

An older PHP for one site#

On macOS, with Homebrew, you can pin a site to an older PHP. The site then runs on Homebrew's php@<version> through php-fpm, behind the same Caddy. Its address, certificate, logs and Caddy rules don't change.

cove php mysite 8.2            # pin it, installing php@8.2 if needed
cove php mysite default        # back to FrankenPHP's PHP
cove add legacy --php=8.1      # pinned from the start

• WP-CLI, artisan and Composer for a pinned site run on the same version.
• The pin lives in the site's php_version file, so it moves with the site through cove clone and cove rename.
• Homebrew has PHP 8.1 and up. For 8.0 or 7.4, add a tap that provides them, such as shivammathur/php, and pinning works the same way.
• The dashboard can pin a site too, from its PHP version menu item.

On Linux every site runs on FrankenPHP's PHP. Pinning needs Homebrew, so it's macOS only for now.

Memory and settings#

Cove keeps its PHP settings in ~/Cove/php.ini. The one you're most likely to change is the memory limit:

cove memory                    # memory_limit everywhere it's set
cove memory set 2G             # raise it

cove memory reports the limit in Cove's ini, in the web server, and in every php on your PATH. set writes memory_limit, upload_max_filesize and post_max_size to Cove's ini, updates the web server, and offers to update each other ini it found, one at a time. --yes updates them all without asking. -1 means no limit.

OPcache#

All your sites share one FrankenPHP, so they share one OPcache. Cove sizes it generously, but a large collection of sites can still fill it, and a full cache makes the site you're working on slow.

cove opcache                   # limits, and whether it's full
cove opcache sites             # what each site takes up
cove opcache set 4096          # resize it, in MB
cove opcache exclude add mysite wp-content/cache

exclude keeps a folder out of the cache, which suits folders full of generated PHP. Resizing and excluding restart FrankenPHP, after asking. A site pinned to an older PHP has an OPcache of its own.

Errors and logs#

PHP errors from every site go to one shared log, ~/Cove/Logs/errors.log. A site's own log comes first when you name it:

cove log                       # the shared PHP error log
cove log mysite                # the site's own log, then its access log
cove log mysite -f             # follow it as it grows

A site's own log is WordPress's wp-content/debug.log or a Laravel app's newest storage/logs/*.log. --app or --access shows just one. The dashboard's logs view shows the same files, parsed and filterable.

Error pages#

When a WordPress or plain PHP site hits a fatal error, Cove shows a Whoops page: the error, the stack trace, and the code around each line. Warnings and notices don't interrupt the page. Laravel apps show their own error page instead.

These pages are for you only. A visitor on your network, your tailnet or a cove share link gets the plain error page, with no code or paths on it.

If FrankenPHP ever crashes rather than showing an error, cove health looks for the reason. cove signals checks and repairs a crash handler one of FrankenPHP's bundled extensions replaces; the watchdog already does this each time the server starts.