Grumphp Shim Laravel Package

Technical Evaluation

Architecture fit

• The shim is a distribution mechanism, not a framework. It ships upstream GrumPHP as a self-contained PHAR exposed at vendor/bin/grumphp.phar, so it slots into existing Laravel/PHP repos without touching application runtime, autoloading, or the production dependency graph. It is a --dev install only.
• The value proposition is narrow but real: GrumPHP pulls a large transitive dependency tree (Symfony components, php-parser, task-specific tooling) that frequently collides with a Laravel app's pinned PHPUnit/Symfony versions. Bundling removes that entire class of composer update conflicts.
• Architectural tradeoff: you trade dependency composability for isolation. You can no longer patch or pin an individual transitive dependency inside the tool — the only lever is upgrading the shim. That is acceptable for a code-quality gate and unacceptable for anything in the request path.
• Version tags track upstream GrumPHP one-to-one (v2.25.0 → GrumPHP v2.25.0), which is a genuine governance win: upgrade planning, CVE triage, and config compatibility can all be reasoned about against upstream release notes.

Integration feasibility

• Install is a single dev dependency; usage is one command. There is no service, no daemon, no credential surface, no infra change. Time-to-first-value on a pilot repo is measured in hours, not sprints.
• Config reuse is the key adoption lever: existing .grumphp.yml/grumphp.yml files carry over unchanged, so teams already on GrumPHP migrate with a dependency swap and a binary rename in scripts and hooks.
• Real integration friction sits in one place: Git hook installation. git:init writes absolute paths into .git/hooks/*, and the recorded path will reference grumphp.phar rather than grumphp. That must be verified per repo, and hooks re-initialized after adoption or the gate silently does nothing.

Technical risk

• Low blast radius (primary mitigant): the package is dev-only and excluded from production artifacts. A failure degrades developer workflow or a CI step; it cannot take down an application. Removal is a one-line composer remove.
• Adoption signal is weak: ~29 stars and zero listed dependents. For a thin shim this is expected — most consumers never appear as dependents for dev tooling — but it means we cannot benchmark against a broad install base. Mitigate with a pilot rather than a fleet-wide mandate.
• Maintainer credibility offsets the metrics: phpro is the GrumPHP upstream maintainer, the shim is released in lockstep with upstream, and recent releases show active PHP-version compatibility work (PHP 8.5 readiness, php-parser v5). This is a first-party convenience layer, not a random fork.
• Opaque artifact: a PHAR is not reviewable line-by-line and will not appear in vendor/ dependency scans. Organizations with binary-artifact allowlists or SBOM requirements will need an exception or an allowlist entry, and that review is a schedule risk, not a technical one.
• Change visibility is poor for the wrapper itself: release notes are mostly "see upstream." Wrapper-specific fixes (e.g., "Fixed an invalid require in the php wrapper", "Disable requirements checker") are buried in one-liners. Anyone bumping the pin must diff carefully rather than trusting the changelog.
• Metadata anomaly: the latest release date reads as future-dated relative to the present. Treat the pin as verified against Packagist/npm-style registry state at adoption time rather than trusting the summary.

Key questions

1. Does the shim's bundled PHP requirement align with our full runtime matrix (local dev images, CI matrix, legacy 8.1/8.2 services)?
2. Is the phar extension enabled and not policy-restricted across our CI images and developer machines (macOS/Linux/Windows/WSL)?
3. Does our supply-chain policy permit an allowlisted binary artifact, and who owns that approval?
4. Who is the named internal owner for bumping the pin, and on what cadence?
5. Do we already have GrumPHP hooks installed directly? If so, which repos need hook re-initialization to avoid a silent no-op gate?
6. Is there an existing alternative already in use (CaptainHook, Husky-style wrappers, editor-integrated Pint/PHPStan) that this would duplicate?

Integration Approach

Stack fit

• Strong fit for Laravel/PHP repos using Composer, Git, and a CI provider. Composes cleanly with Laravel Pint, PHPStan/Larastan, Pest/PHPUnit, and PHPCS via standard GrumPHP task config.
• The same command in the hook and in CI is the important property: one config file, one execution path, no drift between "what developers run" and "what the pipeline enforces."
• Poor fit where GrumPHP is already conflict-free (small dependency surface), where the team is standardized on composer scripts calling tools directly, or in non-PHP repos.

Migration path

1. Inventory repos currently running GrumPHP directly or with hand-rolled pre-commit shell scripts.
2. On one pilot repo: replace phpro/grumphp with phpro/grumphp-shim in require-dev, keep the config file untouched, rename binary references in composer.json scripts and CI steps to vendor/bin/grumphp.phar.
3. Re-run git:init (or the equivalent hook installer) and confirm the committed hook invokes the .phar path; test a deliberately failing commit to prove the gate blocks.
4. Add a CI job running the identical command so the local gate and the pipeline cannot diverge.
5. Roll forward repo-by-repo, then standardize the config via a shared template or preset so tasks and rules are uniform.

• Rollback: delete the line, restore the prior dependency. No data migration, no state, no cutover window. This makes the decision cheap to reverse and cheap to defend.

Compatibility

• Version-locked to upstream GrumPHP: pin to a caret range matching the upstream minor we've validated, and treat upstream minors as the unit of change review.
• Existing .grumphp.yml is honored, so task definitions, ignore lists, and per-task options carry over. Custom tasks that assume a composer-installed autoloader path are the one category to spot-check.
• Watch items: PHP version ceiling of the bundled requirements checker (historically a friction point, explicitly disabled in recent releases), and shell/OS differences in how vendor/bin/grumphp.phar resolves (Windows .bat proxies).

Sequencing

1. Week 0 — validation spike (1–2 days): one repo, hook + CI parity, verify phar works in the CI image, confirm artifact allowlist path.
2. Week 1 — pilot (1 team): measure pre-commit runtime and CI failure rate before/after; collect false-positive friction.
3. Week 2–3 — standardize: publish the shared config template and the composer script alias; document bypass policy (--no-verify exceptions and their review).
4. Week 3–6 — rollout: apply to remaining repos in batches; wire grouped dependency updates so pins move together.
5. Post-rollout — measure: CI failure rate, mean pipeline duration, hook pass rate. Keep or kill on evidence.

Recommendation: adopt as a tactical, dev-only, low-commitment dependency with a pilot gate — not as a platform standard until adoption friction and artifact-review cost are measured. The asymmetric risk profile (trivial rollback, no production exposure) justifies trying it; the thin ecosystem signal justifies not mandating it in one move.

Operational Impact

Maintenance

• Ongoing cost is a mechanical, monthly-ish pin bump tied to upstream GrumPHP releases. Budget roughly an hour per bump per monorepo-level pin, plus a smoke test of the hook.
• Because the PHAR bundles its own dependencies, routine dependency hygiene does not apply to the tool's tree — which cuts maintenance noise but concentrates all upgrade risk into a single version bump. A bump is therefore a small but real change event, not a no-op.
• Config maintenance (task list, rule sets, ignore paths) is the dominant long-term cost, and it is the same cost you would carry with upstream GrumPHP. The shim neither helps nor hurts here.

Support

• No shim-specific documentation beyond a five-line README. All troubleshooting routes to upstream GrumPHP docs and issue tracker, which are adequate but not written for this distribution.
• Practical consequence: internal support will absorb "the hook didn't run" and "it can't find the phar" questions. Mitigate with a short internal runbook covering install, hook re-initialization, binary path, and bypass policy.
• Requires a named owner and at least one champion per team. Without that, hooks rot silently after a composer update and the gate becomes decorative.

Scaling

• Scales linearly and cheaply across repos: one dev dependency each, no shared service to operate. For a monorepo, a single root pin covers everything.
• Cost driver is CI: adding a quality-gate step to N pipelines increases pipeline minutes unless the local hook actually absorbs the failures it is meant to catch. Cache vendor/ and the PHAR download; measure before/after pipeline duration rather than assuming a saving.
• Cross-repo consistency is the real scaling risk, not throughput. Without a shared config template, N repos drift into N different rule sets, which defeats the standardization goal.

Failure modes

• Silent no-op gate (highest likelihood): stale hooks pointing at the old binary path after migration, so commits pass locally and fail in CI. Detect by asserting the hook blocks a known-bad commit during rollout.
• CI environment incompatibility: phar extension missing or disabled, or an image that blocks binary execution. Detect in the spike, not in week 5.
• Policy block: artifact allowlist or SBOM review rejects an opaque PHAR. This is a schedule risk with a governance resolution, not a technical one.
• Deliberate bypass: developers routinely using --no-verify under deadline pressure. Needs an explicit policy and, if it matters, CI enforcement of the same rules as the backstop.
• Upgrade surprise: a caret-range bump pulls in changed upstream task behavior (or a wrapper fix like the invalid-require regression). Mitigate with exact pins plus scheduled, reviewed bumps; do not float the range.
• Corrupt or partially downloaded PHAR in CI: rare, but surfaces as a confusing parse error. Cache and checksum, or fail fast with a clear message.
• Abandonment: low star count means the project could quietly stop tracking upstream. Detectable (release cadence is the signal) and survivable (fall back to direct GrumPHP install with the same config).

Ramp-up

• A developer already familiar with GrumPHP needs about 30 minutes: install, look at the config, done. Total unfamiliarity with GrumPHP is the actual ramp — task authoring, exit codes, and fix-vs-bypass norms — not the shim.
• Realistic estimates: half a day for a first repo including hook verification; 1–2 days to author a solid Laravel task set (Pint/PHPCS, PHPStan at a chosen level, Pest subset) and tune it to near-zero false positives; ~1 hour of team onboarding.
• Predictable early friction: the first week produces noisy failures while rule sets and ignore lists are tuned. Set expectations that the gate will be tightened in stages rather than switched on at full strictness, or the team will route around it permanently.