Grumphp Shim Laravel Package

Product Decisions This Supports

• Build vs. buy for pre-commit quality gates. Rather than maintaining custom shell scripts or Git hook glue, adopt a maintained PHAR wrapper. The build option only makes sense if you need bespoke orchestration that GrumPHP's task config can't express — and even then, the shim can host custom tasks via .grumphp.yml, so "build" is mostly "configure."
• Whether to invest in shift-left quality tooling this quarter. This package is the cheapest possible experiment: one composer require --dev, one YAML file, no application dependency footprint. It's a low-cost way to validate whether local quality gates actually reduce CI churn before committing to a broader platform investment.
• Dependency-conflict policy as a product concern. The shim exists specifically because installing GrumPHP's full dependency tree can collide with an application's vendor/ (PHPUnit, php-parser, Symfony versions). Adopting it is effectively a decision that dev tooling must never constrain runtime dependency choices — which is a meaningful architectural stance for Laravel projects with tight version pinning or long upgrade tails.
• Roadmap input for monorepos and multi-repo estates. If the roadmap includes consolidating several Laravel services or a monorepo, the shim gives a single, uniform quality gate that drops into each repo's CI without per-repo dependency negotiation. That reduces the number of distinct onboarding runbooks you have to maintain.
• CI cost and cycle-time workstream. Pre-commit checks executed locally are CI minutes not spent, and failures surfaced before a PR is opened are review cycles not spent. Treat the shim as a lever in the cycle-time workstream rather than a "linting nice-to-have," and size the benefit against your actual CI volume.
• Onboarding and contributor-experience decisions. For open-source or contract-heavy contributor models, "run vendor/bin/grumphp.phar run and the same checks the maintainers run" is a simpler instruction than "replicate our CI environment." It lowers the cost of the first accepted PR.
• Not a runtime product feature. This is dev-only tooling. It should not appear on a customer-facing roadmap or be pitched as a differentiator; it's an internal engineering-effectiveness decision with a maintenance-cost profile.

When to Consider This Package

Consider adopting when:

• The stack is PHP, and specifically Laravel/Symfony where GrumPHP's task ecosystem (PHPStan/Pint/Pest/PHPUnit/PHPCS) maps cleanly onto tools you already use.
• You have hit, or can foresee, a Composer dependency conflict installing GrumPHP directly — mismatched php-parser, PHPUnit, or Symfony constraints are the canonical trigger.
• You want quality gates but cannot install globally or mutate the project's dependency graph meaningfully (locked-down CI images, shared hosting, Docker images you don't want to rebuild).
• Multiple repos or teams need an identical, versioned gate so results are comparable across services.
• Your platform baseline is modern PHP (GrumPHP v2 requires PHP 8.1+); check that against your least-modern service before standardizing.

Look elsewhere when:

• The stack is non-PHP, or you've standardized on CI-native linting/analysis (GitHub Actions, GitLab CI templates) and don't want a second, locally-duplicated source of truth for rules.
• Your team is small and co-located and the failure mode you're solving (inconsistent local environments) isn't real yet — the hook will be bypassed with --no-verify and the config will rot.
• Adoption risk outweighs the benefit. This is a low-signal package on its own: ~29 stars, zero dependents listed, and it is a thin wrapper whose version numbers simply mirror upstream GrumPHP (v2.25.0 → GrumPHP v2.25.0). Your real dependency is on GrumPHP itself; vet GrumPHP's health and maintainer responsiveness, not the shim's. If GrumPHP's release cadence stalls, the shim stalls with it — the shim cannot patch around upstream.
• You need the tool to be debuggable and hackable in-place. A PHAR is opaque; teams that routinely patch their tooling will find the direct Composer install easier despite the dependency risk.
• You require enterprise support, SLAs, or security-response guarantees. MIT-licensed, single-maintainer-adjacent tooling doesn't offer that.

Mitigation to plan for either way: pin the shim version like any other dev dependency, ensure developers can run the same command in CI (so an environment mismatch is detectable), and decide up front whether hook bypass is allowed and under what conditions.

How to Pitch It (Stakeholders)

Executives — one paragraph, framed as cost and risk, not tooling:

We can add automated code-quality gates to our PHP/Laravel work at essentially zero integration cost. Today, standards enforcement happens in CI, which means we pay for compute to discover problems that a developer could have caught in seconds before pushing. This package lets us run the same checks locally without touching our application's dependencies — the reason we haven't done this already is that the standard tool can conflict with the libraries our product actually depends on. The change is a dev-only dependency, MIT-licensed, requires no new infrastructure, and is reversible in one commit. I'd propose piloting it on one service for a sprint and measuring PR review cycles and CI failure rate before rolling it out. I'd flag honestly that this is a thin wrapper around an open-source project with a small maintainer base — the risk is maintenance continuity, not security or lock-in, and the exit cost is negligible.

Engineering — the practical case, plus the caveats they'll ask about:

• It's GrumPHP as a self-contained PHAR. One composer require --dev phpro/grumphp-shim, then vendor/bin/grumphp.phar run. Config lives in the .grumphp.yml you already know.
• The point is dependency isolation: nothing is added to the runtime dependency graph, so no version arbitration with PHPUnit, php-parser, or Symfony.
• It's a drop-in, not a fork — versions track upstream GrumPHP exactly. Behavior and .grumphp.yml semantics are identical to the direct install; the only difference is packaging. That means documentation, task configs, and tribal knowledge transfer directly, and swapping back to the direct install later is trivial.
• Wire it once: a composer script ("grumphp": "vendor/bin/grumphp.phar run") plus a .git/hooks/pre-commit that calls it, or a CI step in parallel so local and CI can't silently diverge.
• What I'd want the team to own: version pinning and an upgrade cadence (bump the shim when upstream GrumPHP ships), a documented policy on --no-verify, and a decision on whether the PHAR is cached in the CI image. Also: confirm the minimum PHP version across all target services clears GrumPHP v2's requirement.
• Known trade-off: PHARs are harder to debug and patch than a vendor install. If we find ourselves wanting to modify the tool, that's a signal we should reconsider the direct dependency and solve the conflict instead.

Quality/Security stakeholders — brief, and avoid overclaiming:

The gate runs whatever tasks we configure — static analysis, coding-standard checks, test suites — at the point of commit, which means non-compliant code is less likely to reach review. It improves consistency; it is not a security control in itself, and should sit alongside, not replace, dependency scanning and code review. Configuration is version-controlled and reviewable, so what's enforced is auditable.

What I would explicitly not claim: precise percentage reductions in CI failures or CI spend. Those depend on your pipeline volume and current failure mix. Set a baseline first — CI failure rate, mean PR review cycle time, and CI minutes per merged PR — then pilot on one repository and compare. If the numbers don't move, drop it; the switching cost is one commit.