feat(php): consolidated PHP tooling (php, artisan, phpunit, phpstan, pest, paratest, ecs, pint)

[iliaal]

Summary

Consolidates the open and closed PHP-tooling work into a single PR against develop, omitting .phpt (which has its own PR #1503).

This PR adds eight rtk subcommands for PHP test runners and code tooling: php, artisan, phpunit, phpstan, pest, paratest, ecs, pint. Output compression in the 60% to 95% range per tool, structured parsers where possible (PHPUnit state machine, PHPStan typed JSON, Pint per-file rule counts).

Credits to original authors

• @aaronflorey (rtk-ai/rtk#1246, self-closed 2026-04-26): php, artisan, ecs, pest, paratest, test_output, utils, composer_bin_dirs, registry normalization for Composer custom-bin-dir layouts.
• @Beninho (rtk-ai/rtk#874, open): phpunit state-machine parser. I ported it into the consolidated module, switched it to runner::run_filtered, and stripped emoji from output.
• @LucianoVandi (rtk-ai/rtk#1110, open): phpstan typed serde::Deserialize parser for --error-format=json. Groups errors by file, sorts by count descending; passes utility commands (--version, list, clear-result-cache) through unchanged. I stripped emoji from the success output.
• New work: pint (Laravel Pint code-style fixer) using --format=json for structured per-file rule counts.

If the maintainers prefer this consolidation, close the three separate PRs in favor of this one. If they prefer the originals, close this PR and let the per-tool PRs continue independently. Either is fine with me.

Composer custom-bin-dir support

composer_bin_dirs() reads COMPOSER_BIN_DIR and composer.json's config.bin-dir, so tools/bin/phpunit classifies identically to vendor/bin/phpunit. registry.rs normalizes tool paths before matching, so a single rule covers the standard Composer layouts.

[pszymkowiak]

[w] wshm · Automated triage by AI

📊 Automated PR Analysis

✨ Type	feature
🟡 Risk	medium

Summary

Adds eight new rtk subcommands for PHP tooling (php, artisan, phpunit, phpstan, pest, paratest, ecs, pint) with structured output parsers and compression. Consolidates work from three prior PRs by different authors into a single module, including shared test output filtering, Composer custom-bin-dir support, and registry normalization.

Review Checklist

• Tests present
• Breaking change
• Docs updated

Linked issues: #1503, #1246, #874, #1110

---

Analyzed automatically by wshm · This is an automated analysis, not a human review.

[pierresh]

Hi,
Thanks a lot for this consolidated PHP tooling. I tested it, and it works well. Just 2 suggestions: to add Behat and Rector as they are both popular tools in the PHP world.

[iliaal]

Hi, Thanks a lot for this consolidated PHP tooling. I tested it, and it works well. Just 2 suggestions: to add Behat and Rector as they are both popular tools in the PHP world.

Can be added maybe as a follow-up, PR is already quite big, but 100% a good idea.

[iliaal]

Added f9e139a on top of this branch: swaps the make filter from max_lines = 50 (head-only) to head_lines = 10 + tail_lines = 40, so make test runs (e.g. PHPT, which puts ~17000 progress lines before the pass/fail summary) keep both the prologue and the trailing summary instead of dropping the latter.

Companion fix at the recovery layer: #1696 — same head-bias bug in write_tee_file, where the tee log capped at 1MB by keeping raw[..1MB]. With both landed, tail-heavy output survives at the filter and at the fallback log.

[webagil-kevin]

Tested this branch on a production Symfony monorepo (27 packages, PHP 8.4/8.5, Pest 4.6.3 + PHPStan level 9), built from source and wired through the Claude Code PreToolUse hook.

Works well across the toolchain:

• rtk pest / rtk phpunit — failures + summary only, drops the passing noise while preserving diffs and file:line
• rtk phpstan — compact file:line errors instead of the full table + preamble
• rtk pint, rtk php artisan test — resolve and filter as expected
• vendor/bin/* rewrites and php artisan* routing all behave correctly
• cargo test is green on the branch (2035 passed)

Coverage matches our PHP stack exactly and the filtered output stays faithful to each tool's native format. Would love to see this land — happy to help test further. Thanks for the thorough work here.

[EliW]

Really looking forward to this landing as part of rtk. It's needed to get real benefits from rtk for those of us on PHP monoliths at the moment :)

Pretty please?

[KuSh]

Hi @iliaal,

Since you're aggregating contributions from others in this PR, please ensure you include the "Co-authored-by:" trailer in the commit message to properly credit them.

Example:

Co-authored-by: Name <email@example.com>

This helps maintain proper attribution for all contributors. Thanks!

[CLAassistant]

All committers have signed the CLA.

[evaldnet]

Tried this branch locally against current PHP tool versions (Pint 1.27.1, PHPStan 2.1.40, ECS 13.0.4) — great work, the savings are substantial. I hit two parser bugs where the expected schema no longer matches what current tooling emits. Both stem from test fixtures using an older schema, so the suite stays green. Details + fixes below.

1. pint — JSON field names changed (name/appliedFixers → path/fixers)

PintFile requires name + appliedFixers, but Pint ≥ ~1.14 (confirmed on 1.27.1) emits:

{"result":"fail","files":[{"path":"app/Foo.php","fixers":["concat_space"]}]}

The fields are required with no aliases, so serde rejects it and filter_pint_json falls back to raw output — no compression. Fix is backward-compatible aliases:

#[serde(alias = "path")]
name: String,
#[serde(rename = "appliedFixers", alias = "fixers")]
applied_fixers: Vec<String>,

2. phpstan — reports phpstan: ok while errors exist ⚠️

filter_phpstan_json gates the "ok" case on totals.errors == 0, but PHPStan puts per-file errors in totals.file_errors and leaves totals.errors (global/config errors only) at 0. A real run with 78 file errors — {"totals":{"errors":0,"file_errors":78}, ...} — returns phpstan: ok, silently hiding the failures (the summary line under-reports for the same reason). Note file_errors is currently #[allow(dead_code)]. Fix:

if phpstan.totals.file_errors == 0 && phpstan.totals.errors == 0 { return "phpstan: ok".to_string(); }
// and report phpstan.totals.file_errors in the summary line

Both fixtures set errors == file_errors (phpstan) / use the old field names (pint), which is why tests don't catch these. Happy to open a PR against this branch with both fixes + regression tests using the current-version schemas if that's useful.

[iliaal]

Thanks for the precise report, @evaldnet — both confirmed and fixed on this branch (184ced3).

• pint: added backward-compatible serde aliases (path/fixers) so current Pint output compresses again instead of falling back to raw.
• phpstan: the ok gate and summary now read file_errors, so runs with file-level errors no longer report phpstan: ok.

Both ship with regression tests on the current-version schemas — the old fixtures set errors == file_errors and used the old pint keys, which is why the suite stayed green.

[EliW]

@evaldnet Thanks for finding those. --- out of curiousity @iliaal --- Does this mean that the code here now may depend on which version of phpstan you are using for example? Or did I grok that incorrectly. Some folks end up stuck on older phpstan's due to framework incompatibilities at times...

[iliaal]

@EliW No. Both old and current tool output parse; I checked each schema against the new code.

pint: the fix adds serde aliases, not a rename. The struct accepts both the old keys (name/appliedFixers) and the current ones (path/fixers), so it parses Pint from either side of the ~1.14 rename. Before, only the old schema parsed and current Pint fell back to raw. Confirmed: old-key and new-key JSON both compress.

phpstan: no new version dependency. totals.errors and totals.file_errors have both been in the --error-format=json output since at least 0.12, unchanged through 1.x and current 2.1.40. errors counts non-file-specific errors, file_errors counts file-specific ones. The parser already required file_errors, it was just unused. The bug read errors where it should read file_errors, which is correct on old and current PHPStan alike.

Safety net under both: if the JSON ever fails to parse, rtk falls back to raw tool output. You lose the compression for that run, not the result. So anyone stuck on an older phpstan or pint won't get broken output; worst case is unfiltered passthrough.

[evaldnet]

Rebuilt on 184ced3 and re-ran against current versions. Both fixes hold:

• phpstan (2.1.40): file-level errors now report instead of "phpstan: ok".
• pint (1.29.1, the new path/fixers keys): an 8-fixer file compresses to "pint: 8 changes in 1 files" with the rule list.

One separate thing I noticed while testing: the leading ./ form isn't matched for most tools, so it runs raw with no compression.

• ./vendor/bin/pint runs raw, while vendor/bin/pint rewrites to rtk pint. Same for pest, paratest, ecs, phpunit.
• The phpstan pattern already handles this with an optional \.?/? prefix (it also requires the analyse subcommand). The other five patterns are ^(?:vendor/bin/)?<tool>, so a leading ./ defeats the match.

Since ./vendor/bin/... is how most people invoke these in Laravel, adding the same \.?/? prefix would close it.

[iliaal]

Fixed on the branch (bd91048). One correction on the mechanism: the regex isn't the blocker. classify_command already normalizes a leading ./ (normalize_php_tool_path strips it), so ./vendor/bin/pint classifies fine without \.?/? in the pattern. The gap is the rewrite step, which strips literal rewrite_prefixes from the raw command. The five rules only carried vendor/bin/<tool> and bare <tool>; phpstan works because ./vendor/bin/phpstan is in its prefix list, not its regex. Fix adds ./vendor/bin/<tool> to the five lists, with a regression test covering ./vendor/bin/{pint,pest,paratest,ecs,phpunit}.

[iliaal]

Rebased onto current develop (this branch was ~50 commits behind) and fixed the two CI failures:

• test (test_every_subcommand_is_classified): develop added this test plus the PASSTHROUGH const after this branch forked, so the merged tree had the php subcommands with no classification entry. Added php/phpunit/phpstan/pest/paratest/ecs/pint to PASSTHROUGH.
• semgrep (dynamic-command-execution): php_tool_command built the command via Command::new on a resolved path. Routed it through resolved_command (the sanctioned PATHEXT-aware constructor) instead — no behavior change.

The six php-tooling commits replayed with zero conflicts. Locally: test_every_subcommand_is_classified passes, fmt/clippy clean, full suite green. The semgrep fix I verified by inspection (no Command::new(<var>) left in the php dir); CI will confirm.

Heads up: the workflow run on the new head is sitting in action_required — it needs a maintainer to approve before test/semgrep execute.

[KuSh]

Code Review — feat(php): consolidated PHP tooling

Review performed using Claude Code (claude-sonnet-4-6) by the RTK maintainers.

This is a solid and well-scoped contribution. The PHPUnit state machine, the PHPStan errors vs file_errors distinction, and the Pint dual-schema handling via serde aliases are all done correctly and are well-tested. The php_tool_command() abstraction for Composer-aware binary resolution is the right design.

That said, there are three blocking bugs and two maintainability issues to address before merge.

---

🔴 Blockers

1. filter_phpstan_text: "not found" is dangerously broad (inline comment on phpstan_cmd.rs:165)

2. phpstan_cmd.rs bypasses php_tool_command() (inline comment on phpstan_cmd.rs:48)

3. is_numbered_failure_heading() has false positives (inline comment on phpunit_cmd.rs:89)

---

🟡 Should-fix

4. compact_php_path() is Laravel-only (inline comment on phpstan_cmd.rs:192)

5. short_path() calls current_dir() in a per-file loop (inline comment on pint_cmd.rs:126)

---

What's working well

• PHPStan errors vs file_errors bug is correctly identified and tested (test_filter_phpstan_file_errors_not_hidden) — this was a real prior bug fixed here
• PHPUnit state machine correctly handles success, multi-failure, errors, skipped, and truncation cases with 9 test cases
• Pint dual-schema serde aliases (name/appliedFixers vs path/fixers) cleanly handle the Pint ≥1.14 rename
• php_tool_command() centralises Composer bin-dir resolution correctly — pity PHPStan doesn't use it (see inline comment)
• Token savings are verified against a real 380-line phpstan_raw.json fixture, not synthetic data
• No unwrap() in production paths, fallback pattern respected throughout

[KuSh]

Hi @iliaal, this looks mostly good to me, just a few minor nitpicks and suggestions. Sorry the PR is a bit huge; I wasn’t able to review it all in one go

[KuSh]

Could you add tests for paratest? That’s what’s causing the CI failure. See .claude/rules/cli-testing.md for the full testing guide. After that, LGTM!

[iliaal]

Added in fe75595. paratest_cmd.rs was missing the mandatory #[cfg(test)] module — that's what tripped the check-test-presence gate. The two tests exercise the ParaTest-specific branch of filter_test_runner_output (banner, Random Seed:, and dot-progress stripped; result summary and failure details preserved), rather than duplicating pest's coverage.

Verified locally: bash scripts/check-test-presence.sh origin/develop now passes all 9 modules, fmt/clippy clean.

[KuSh]

LGTM, thanks for all the work!