Coverage and mutation testing must both pass at 100%. Always run both after making changes.
# Coverage
herd coverage ./vendor/bin/pest --coverage
# Mutation testing
herd coverage ./vendor/bin/pest --mutate --parallel --everything --covered-onlyBoth are also wired as composer scripts with the thresholds attached, so the gate is the same locally and in CI. On this machine use the -local variants, which wrap the same commands in herd coverage; the plain ones need a coverage driver already enabled in the PHP binary and are what CI runs.
composer check-local # analyse + coverage + mutation, via herd
composer check # same, needs Xdebug/PCOV enabled
composer analyse # phpstan only, no driver neededNote the mutation scripts omit --parallel on purpose — see the decision log.
PHPStan runs at level max against src/ and must report zero errors. No ignoreErrors and no @phpstan-ignore comments — fix the underlying type shape instead.
./vendor/bin/phpstan analyseSettled calls worth not re-litigating. This file is the log — there is no separate decisions file.
- WordPress parity is considered complete. Deregistration shipped in 2.12.0 (
removeAction,removeFilter,removeAllActions,removeAllFilters) and introspection right after (hasFilter/hasAction,didFilter/didAction,currentFilter/currentAction,doingFilter/doingAction). What is left in WordPress is either array-variant sugar made redundant by variadics (apply_filters_ref_array,do_action_ref_array) or global-registry behaviour that does not apply to an instance-based library (theallhook,merge_filters). Do not add more WP verbs speculatively — wait for a consumer to ask. - Deregistration matches WP, plus a nullable priority.
removeFilter/removeActiondefault to priority10and only touch that bucket, exactly likeremove_filter()in WordPress, so WP users get no surprises. Passingnullas the priority is a deliberate extension that strips the callback from every priority of the hook, for callers who do not want to track registration priorities themselves. Rejected: callback-identity-only removal (cannot target one of two registrations of the same callback) and strict WP parity with no null (forces callers to bookkeep priorities). - Callbacks are matched by identity (
===), not normalized. AClass::methodstring does not match a[Class::class, 'method']array registration, unlike WordPress, which normalizes both to a single id. Normalization would mean hashing callables on everyaddFiltercall; identity matching keeps registration free and is sufficient when the caller holds the reference it registered. Documented in the README so the limitation is explicit. - Removal during dispatch does not affect the in-flight run.
applyFilter'sforeachiterates a copy-on-write snapshot of the priority buckets, so a callback that removes a later callback does not prevent it from running in that same dispatch; the change applies from the next dispatch. WordPress re-reads and would skip it. Changing this means restructuring the dispatch loop, which was not worth it — the behaviour is tested and documented rather than left implicit. - Sonar is advisory; it must never gate a release. The scan runs in its own
sonarjob withcontinue-on-error: true, andreleasedepends only ontest. This is not a style preference — an expiredSONAR_TOKENproduced an HTTP 403 before a single file was analysed and blocked the 2.12.0 release on 2026-10-30, even though PHPStan, the suite, coverage and mutation all passed. The real gates live in thetestjob; Sonar is a second opinion on top of them. composer auditfindings here are usually local staleness, not a repo problem. Because no lock file is committed, CI resolves the newest versions inside the declared constraints on every run, so an advisory against an installed dev dependency normally means the localvendor/is old — not that CI or any consumer is exposed. That is exactly what the two 2026-10-30 advisories were (phpunit/phpunitCVE-2026-24765 high,symfony/processCVE-2026-24739 medium): both cleared with a plaincomposer update, no constraint change needed. Check whether the constraints already permit a patched version before touchingcomposer.json. And note dev-only advisories never reach consumers of this library — nothing inrequirebut PHP itself.phpunit/phpunitis a direct dev dependency on purpose. CI and the composer scripts invoke./vendor/bin/phpunit(it is the deprecation gate), andphpunit.xmlconfigures it, so relying on it arriving transitively through Pest was wrong — the binary we call directly should be declared directly. The floor (^11.5.56) also sits above CVE-2026-24765. The cost is that a Pest major bump now has to move this constraint in the same commit, which is visible rather than surprising.- Deprecations, warnings and notices fail the suite.
phpunit.xmlsetsfailOnDeprecation,failOnNoticeandfailOnWarning. This was added after the PHP 8.4 matrix leg surfaced a deprecation insrc/that had been passing CI unnoticed for months: PHPUnit reports deprecations but exits 0 by default, so "1 deprecated" in the summary meant nothing. Note that only thephpunitbinary honours these flags — Pest prints the same deprecations and still exits 0 — so theRun tests with phpunit/phpunitCI step is the real gate, not the pest steps. Consequence to accept: because CI resolves dependencies without a lock file, a dev dependency that starts emitting a deprecation can turn CI red with no commit of ours. - The single-argument
ReflectionMethodconstructor is avoided deliberately.validateCallbackTypeHints()splits a"Class::method"callable withstrpos/substrand uses the two-argument constructor. The one-argument form is deprecated in PHP 8.4, and its replacementReflectionMethod::createFromMethodName()does not exist before 8.4, so with a^8.2floor the two-argument form is the only variant valid on every supported version. Do not "simplify" it back. - Mutation testing runs serial everywhere it is automated.
--parallelonly works when pest is invoked directly in an interactive shell. Spawned through composer — and therefore anywhere a script or CI step wraps it — the workers do not inherit the coverage-enabled environment, so--covered-onlyfinds nothing and the run reports0 Mutations for 0 Files created/Score: 0.00%rather than erroring. Combined with--min=100that is a hard failure, so it fails loudly rather than passing a lie, but it blocks a release for no reason. The composer scripts and the CI step therefore omit--parallel: 43s serial versus 5s parallel on 158 mutations, which is a fine trade for determinism. The hand-run command at the top of this file keeps--parallelbecause typing it in a terminal does work. - CI enforces the 100% gates, it does not just report them. The
testjob runspest --coverage --min=100andpest --mutate ... --min=100, both of which exit non-zero below the threshold (verified). Before this, CI ran the suite and generated a coverage report but nothing checked the numbers, so the quality bar this file states was enforced only by whoever remembered to run it locally. hasFilterreturnsbool, not WP'sint|false. WordPress'shas_filter()returns the priority when a callback is found andfalseotherwise, a union that is awkward under PHPStan at max and easy to misuse with a loose comparison (priority0is falsy). We return a plainbooland let the caller pass the priority in as the third argument. If "which priority is this callback at?" is ever actually needed, add a separategetPriority(): ?intrather than overloading the return.- Introspection verbs ship as
*Filter/*Actionalias pairs.hasFilter/hasAction,didFilter/didAction,currentFilter/currentAction,doingFilter/doingAction. All eight names exist in WordPress, and the library already pairsaddAction/addFilterandremoveAction/removeFilterthis way, with the filter variant implementing and the action variant forwarding. SincedoActionforwards toapplyFilter, the two halves of each pair are genuinely the same thing — including thedidFilter/didActioncounter, which is shared per hook name. composer.lockis not committed, and the old backlog entry claiming otherwise was wrong.git log --all -- composer.lockis empty: it has never been tracked, and.gitignorehas ignored it all along. The keep-or-drop decision is therefore already settled in favour of "drop", which is the norm for libraries. Note the consequence: CI runscomposer installwith no lock file, so every run resolves the newest versions inside the declared constraints. For a library that is a feature — it catches breakage against what consumers will actually get — but it does mean CI is not byte-reproducible, and a dependency release can turn CI red without a commit.didFiltercounts dispatches, not deliveries. The counter is incremented at the top ofapplyFilterbefore the no-callbacks early return, so a hook that nobody listens to still counts as fired, matchingdid_action()in WordPress. Removing callbacks does not reset it.Hook::forgetEmptyHook()exists for memory hygiene, not behaviour. An emptied hook is already indistinguishable from an unregistered one through the public API (getMinPriorityreturnsnull,applyFiltershort-circuits on a falsy bucket, andaddFilterclears the sort marker on every add). Pruning keeps$filtersand$sortedHooksfrom growing in long-running processes. Its tests assert the internal arrays via reflection because nothing else can observe it.
Discussed but not yet done. Pick these up as maintenance opportunities.
Recommended order, as of 2026-10-30 (after 2.13.1): runtime $acceptedArgs deprecation first — self-contained, ships a real signal to callers before the parameter is removed, and the PHP matrix is now in place to confirm trigger_error behaves the same on 8.2 through 8.4. Then the Pest 3 → 5 jump, on a branch, because it is the one change that can break the quality gates themselves. The composer.json version field is a five-minute decision whenever you want it. Leave requireTypedParameters until a 3.0 is actually on the table; it is the only item here that breaks consumers, so it should not be done piecemeal.
requireTypedParametersis a magic string. It is plucked out of...$argby name inHook::applyFilter, which works only because variadics collect named arguments. It silently collides with any hook that wants an argument of that name, and it is invisible in the signature. A dedicated method or an options object would be honest; changing it is a breaking change, so it needs a major.- Runtime
$acceptedArgsdeprecation. The parameter is marked@deprecated No longer used - kept for backwards compatibilityinHook::addAction/Hook::addFilterand theirHookInterfacecounterparts, but nothing tells users at runtime. Emittrigger_error(..., E_USER_DEPRECATED)when it's passed as a non-default value, so callers get a real signal before it's removed in a future major. pestphp/pestis a major behind. Constrained at^3.8with 3.8.7 installed; 5.3.4 is out. The jump needs care, since the mutation-testing flags and thresholds this repo depends on changed across majors, and Pest 5 moves to a newer PHPUnit line — sophpunit/phpunitinrequire-devhas to move with it. Do it on a branch and let the full matrix verify it.composer.jsoncarries aversionfield.composer validate --strictwarns against it for a Packagist-published package, but.releaserc.jsonhas semantic-release rewrite it on every release viajq. Removing it means changing the release pipeline to stop writing it; keep-or-drop is a real decision, not a cleanup.