Skip to content

Coverage ​

yerd coverage runs your default PHP version with the bundled pcov line-coverage driver enabled, then forwards everything after the coverage subcommand verbatim to PHP. It is the discoverable front door to the phpcover shim - the same coverage mechanism, but reachable from yerd --help without the shim directory on your PATH.

Like elevate/path, it does not map to an IPC request: it execs PHP directly in your terminal (inheriting your stdin/stdout/stderr, arguments, and exit code) rather than asking the daemon to do anything. (Attempting to route it over IPC is an explicit usage error.)

sh
yerd coverage [ARGS...]
CommandDescription
yerd coverage [ARGS...]Run the default PHP version with pcov enabled, passing ARGS to PHP.
sh
yerd coverage artisan test --coverage         # Laravel / Pest / PHPUnit
yerd coverage vendor/bin/phpunit --coverage-text
yerd coverage -r 'var_dump(extension_loaded("pcov"));'   # prints bool(true)

The process exit code is PHP's own, so yerd coverage composes in CI exactly like the interpreter it wraps.

Need Xdebug's coverage driver instead?

pcov is line coverage only. For path/branch coverage, run your suite under the Xdebug debug shim with XDEBUG_MODE=coverage phpdebug vendor/bin/phpunit --path-coverage. It is slower than pcov; see Debugging with Xdebug and yerd xdebug.

Pinning a version ​

yerd coverage always tracks your global default version. To pin coverage to a specific version, use that version's cover shim directly instead:

sh
php8.4cover vendor/bin/pest --coverage
php8.5cover artisan test --coverage

Passthrough behaviour ​

Everything after the coverage subcommand is handed straight to PHP, so flags belong to your script or test runner, not to yerd:

  • A leading yerd coverage --help (or -h) prints yerd's own help for the command, because --help is yerd's built-in flag. To forward --help to your script, put it after the script name: yerd coverage artisan --help.
  • Every other flag - including --version and the global --json - is passed through to PHP. yerd coverage therefore produces PHP's output, never a JSON daemon response, and --json has no effect. This is the one command where the "--json on every command" note in the overview does not apply.

Environment ​

The three coverage front doors - yerd coverage, phpcover and php<version>cover - set YERD_COVER=1 in the environment of the PHP process they exec, and every process it spawns inherits it.

VariableValueEffect
YERD_COVER1The plain php / php<version> shims load pcov for the version they resolve, instead of the clean per-version ini.
YERD_COVERunset, empty, 0, anything elseNo effect - the plain shims behave normally.

Only the literal value 1 enables coverage; the reading is deliberately narrow so a stray value can't silently instrument every PHP run. Set it yourself for test runners that spawn their own PHP processes rather than running under a cover shim:

sh
YERD_COVER=1 vendor/bin/phpunit-watcher watch

If pcov isn't available for the version a plain shim resolves - a legacy version, or a build not fetched yet - the shim prints a one-line notice on stderr and runs the command normally, without coverage. It does not fail. Only the php / php<version> shims honour the variable: the wp, composer and laravel shims and yerd exec set their own PHPRC regardless. See Code Coverage · Enabling coverage with YERD_COVER.

Failure modes ​

These apply to the coverage front doors - yerd coverage and the phpcover / php<version>cover shims - which fail rather than run without coverage. They do not describe the YERD_COVER path above, where a plain shim falls back to a normal run instead.

  • If the resolved default version has no published pcov build for your OS and architecture yet, yerd coverage reports that pcov isn't installed for that version rather than running without coverage. The background fetch is best-effort and never blocks a PHP install.
  • No legacy support. pcov is not built for legacy PHP versions (7.4 / 8.0 / 8.1, PHP < 8.2). yerd coverage, phpcover, and the versioned php7.4cover / php8.0cover / php8.1cover shims all error on a legacy version rather than run.
  • Unix only. Coverage is available on macOS and Linux; it is not generated on other platforms.

See also ​

  • Code Coverage guide - how pcov is bundled and how the cover shims work.
  • PHP - installing versions and setting the global default that yerd coverage tracks.
  • Xdebug - the phpdebug shim, for Xdebug-based coverage.

A Forjed project. Released under the MIT License.