Commands

phil-dev runs from the root of a package or a monorepo; PHIL_DEV_ROOT names another root. Every command takes --skip-planned, which leaves the planned packages out, as PHIL_DEV_SKIP_PLANNED=1 does; see Configuration.

init

Writes, if missing: phil-dev.php, .php-cs-fixer.dist.php, rector.php, arkitect.php, phpstan.neon, phpunit.dist.xml, phpbench.json, captainhook.json, composer-dependency-analyser.php (for a package) and vendor-bin/<tool>/composer.json for each tool: PHP-CS-Fixer, PHPStan, Rector, Deptrac, Arkitect, Infection, PHPBench, Psalm, php-fuzzer, the CycloneDX plugin, the backward-compatibility checker, TwigStan and Twig-CS-Fixer, Biome, composer-unused, composer-normalize, CaptainHook and churn-php. Each thin file calls the shared one of this package with its own directory; see Configuration.

It adds to composer.json the scripts, their descriptions, bamarni/composer-bin-plugin, brianium/paratest, ergebnis/phpunit-slow-test-detector, phpunit/phpunit and shipmonk/composer-dependency-analyser in require-dev, the plugin's settings and config.process-timeout: 0. The scripts it adds go at the end of scripts: run composer deps:normalize:fix afterwards, as the deps:normalize gate sorts them. A file or a value already identical is left alone; one that differs is kept and reported, and --force replaces it. The phpunit.dist.xml lists the test directories that exist when it is written, and the packages/* globs in a monorepo; it requires the coverage metadata of every test, registers the slow-test detector, and the SymfonyExtension of symfony/phpunit-bridge when the bridge is installed.

new

new phil/example writes packages/example in a monorepo, or example elsewhere; new tilttek/example writes packages/tilttek-example. --bundle writes a bundle and adds -bundle to the name when it is missing; a name that ends with -bundle is a bundle without the option. Only the phil and tilttek vendors are accepted: the wording of each is in the templates. A directory that exists and is not empty is refused.

vendor/bin/phil-dev new tilttek/cards --planned --requires=tilttek/dice --title="Cards" \
    --description="Decks of cards. Shuffled, dealt and drawn, with the history of each draw." \
    --description-fr="Des paquets de cartes. Mêlés, distribués et piochés, avec l'historique de chaque pioche."

check-docs

Runs the checks of The package skeleton on each member of a monorepo, or on the package at the root; PHIL_DEV_PACKAGES or the arguments narrow the members. The terms no package names are the regular expressions of the root's docs.forbidden and of each --forbid.

check-translations, stamp-translations

check-translations compares README.md and doc/**/*.md with README.fr.md and doc/fr/**: a document without its mirror, a mirror without its document, the number of headings of each level and the code blocks fail; a translation behind its English is reported. A package whose docs.translations, else the root's, is advisory never fails, and is summed up on one line; -v lists its findings. stamp-translations writes the SHA-256 of the English on the first line of each mirror of the packages it names; --file narrows it to documents given by their English or French path. See Quality gates.

check-packages

The gates of a monorepo cover the code of its packages, not their composer.json: the root's dependencies hide a require a package forgot. This command copies each package into a temporary directory, leaving out vendor/, var/ and composer.lock, gives the copy a path repository on each glob of the root's packages — copied, not linked —, installs it, runs composer-dependency-analyser with the package's own configuration, then PHPUnit with the package's own configuration when it has one, else phpunit --no-configuration tests. A failure is reported and the next package is checked. --keep keeps the copies.

The path repositories install each member at the branch its branch alias names (dev-main, aliased 0.1.x-dev), whatever branch the checkout is on: from a worktree on b/topic, Composer would otherwise read dev-b/topic, which no alias covers and no ^0.1@dev of a sibling accepts. Each step runs with TMPDIR inside the copy, so that its test kernels never share a cache with another checkout's.

--symfony=VERSION (a version of the matrix, floor or next) pins, in the copy, every symfony/* requirement written at the floor (^8.2) to VERSION.* and lets release candidates in: the package is tested on that Symfony without touching its composer.json. See The version matrix.

infection

Generates var/phil-dev/infection.json — see Quality gates — and runs Infection on the Unit suite with all threads. --changed mutates only the PHP files added or modified since the point where the branch left the base ref, committed or not: the ref given, else PHIL_DEV_BASE_REF, else origin/main when it exists, else main. Nothing changed passes. Arguments after -- go to Infection.

deptrac, witnesses, generate

deptrac writes var/phil-dev/deptrac.yaml (see Dependencies), runs Deptrac on it with --fail-on-uncovered --report-uncovered, then on each file of the root's deptrac.configs. witnesses runs PHPStan on every tests/Witnesses/PhpStan directory with the forbidden calls only; see Quality gates. generate only writes the generated configurations, to read them.

test

Runs the suites of phpunit.dist.xml with ParaTest, one process per core, when vendor/bin/paratest exists; else with PHPUnit. The root's 'phpunit' => ['parallel' => false] keeps PHPUnit, for tests that share a resource they cannot share at once. --suite runs one suite; arguments after -- go to the runner. Infection always replays the Unit suite with PHPUnit. While the planned packages are skipped, test and infection read var/phil-dev/phpunit/phpunit.xml, the root's configuration without them.

test, infection and services test|record run with TMPDIR under var/tmp/ of the root, unless it already points inside the root: the test kernels that keep their cache under the system's temporary directory get one per checkout, and a clone and its worktrees can run their tests at the same time.

audit, unused, normalize, twig, js

The gates added to composer gates, each turned off by 'gates' => ['<name>' => false] in the root's phil-dev.php: see Quality gates. normalize --fix, twig --fix and js --fix apply the fixes.

taint, fuzz, sbom

See Security checks.

twigstan, bc

twigstan writes var/phil-dev/twigstan.php and its PHPStan configuration, then runs TwigStan: see Quality gates. bc compares the public API with the latest tag of the root's bc.tags glob, every tag by default; a repository without a tag passes, and a monorepo leaves the check to the split repositories of its members, where their tags are.

bench, bench:worker

See Benchmarks.

split, lint-docs, hotspots

See The monorepo workflow.

services, php, matrix

See Real servers, HTTP recordings and The version matrix.