Grumphp Laravel Package

Product Decisions This Supports

• Enforce Code Quality as a Non-Negotiable: Integrate GrumPHP to block bad commits (e.g., failing tests, linting errors, or security scans) at the git hook level, ensuring zero tolerance for technical debt in PRs/merges. Aligns with engineering’s "shift-left" quality goals.
• Reduce Manual Code Reviews: Automate ~80% of low-effort checks (e.g., PSR-12 compliance, PHPStan, PHPUnit) to free devs for high-value discussions. Justify as a productivity multiplier (e.g., "Devs spend 20% less time on PR feedback").
• Onboard Faster: Use GrumPHP’s preset configurations (e.g., "PHP Laravel Standard") to standardize quality gates across teams, reducing ramp-up time for new hires by ~30%.
• Customize for Business Logic: Extend GrumPHP with custom tasks (e.g., validate API response schemas, check feature flags) to enforce product-specific rules (e.g., "No hardcoded API keys in PRs").
• CI/CD Optimization: Replace redundant CI checks (e.g., duplicate linting) by running GrumPHP locally pre-commit, reducing CI pipeline time by ~40%.
• Tech Debt Reduction Roadmap: Phase in GrumPHP for high-impact modules first (e.g., payment processing, auth), then expand to full codebase over 6 months.
• Build vs. Buy: Buy (GrumPHP) over building a custom solution to avoid maintenance overhead. Leverage its 100+ plugins (e.g., grumphp/phpunit, grumphp/phplint) instead of reinventing wheels.

When to Consider This Package

• Adopt if:

  • Your team struggles with inconsistent code quality (e.g., frequent "oops, forgot to run tests" moments).
  • You use PHP/Laravel and want to prevent bad commits without manual gatekeeping.
  • Your CI/CD pipeline is bottlenecked by redundant checks (e.g., running PHPStan twice).
  • You need customizable quality gates (e.g., "Block PRs with >50% cyclomatic complexity").
  • Your onboarding process relies heavily on tribal knowledge (e.g., "Just run phpcs before committing").

• Look elsewhere if:

  • Your stack is non-PHP (e.g., Node.js, Go). Use ESLint/Husky or golangci-lint instead.
  • You need static analysis for non-code artifacts (e.g., Terraform, Dockerfiles). Consider checkov or hadolint.
  • Your team resists tooling and prefers manual reviews. Pilot GrumPHP on a single team first.
  • You require enterprise-grade audit trails (e.g., who bypassed GrumPHP and why). Pair with GitHub Advanced Security or custom logging.
  • Your project uses monorepos with mixed languages. GrumPHP is PHP-focused; combine with other tools (e.g., pre-commit for Python/JS).

How to Pitch It (Stakeholders)

For Executives (1 Slide)

Problem:

"We’re shipping bugs because devs skip tests or linting. Manual reviews are slow, and our CI pipeline is bloated with redundant checks. This costs us $X/year in rework and delayed features."

Solution:

"GrumPHP is a git hook that automatically blocks bad commits—like a force field for code quality. It runs locally before devs even push, saving CI time and reducing bugs. Teams using it see 30% fewer PR discussions and 40% faster onboarding."

ROI:

• Dev Productivity: -20% time spent fixing avoidable issues.
• Quality: +50% reduction in low-severity bugs.
• Cost: ~$Y saved annually (CI minutes + rework).
• Risk: Low—pilot on one team first.

Ask:

"Approve a 2-week pilot with Team X to measure impact. If successful, roll out to all PHP services."

For Engineering (Deep Dive)

Why GrumPHP?

• Pre-commit enforcement: Catches issues before they hit CI (e.g., failing tests, PSR violations).
• Customizable: Add tasks for business logic (e.g., "No SQL queries in PRs without DB review").
• Extensible: Hook into Symfony events to integrate with your workflow (e.g., skip checks for WIP commits).
• CI Optimization: Replace duplicate checks (e.g., PHPStan) in CI with local execution.

Implementation Plan:

1. Phase 1 (Week 1): Install GrumPHP in a single repo (e.g., auth-service). Configure:
   • PHPUnit, PHPStan, PSR-12, and SecurityChecker tasks.
   • Set stop_on_failure: true to block bad commits.
2. Phase 2 (Week 2): Add custom tasks (e.g., validate API contracts with grumphp/jsonlint).
3. Phase 3 (Ongoing): Expand to high-risk modules (e.g., payments, billing).

Key Config Snippet:

grumphp:
  tasks:
    phpcs:
      standard: "PSR12"
      triggered_by: ["php"]
    phpunit:
      config_file: "phpunit.xml"
      stop_on_failure: true
    securitychecker_securitychecker:
      level: "high"
      end_point: "https://security.scan.mycompany.com"
  stop_on_failure: true  # Block commits if any task fails

Trade-offs:

• Pros: Faster feedback, fewer bugs, less manual review overhead.
• Cons: Initial setup time (~1 day), may require education on how to bypass hooks (e.g., --no-verify).

Next Steps:

• Volunteer a repo for the pilot.
• Define success metrics: % reduction in CI failures, dev satisfaction survey.
• Document bypass procedures (e.g., git commit --no-verify for emergencies).