Product Decisions This Supports
- CI quality-gate strategy: Decides whether code-quality enforcement lives in the pipeline as a blocking check or as advisory signal. This package produces the GitLab Code Quality JSON artifact, which is what makes MR-level widgets, inline annotations on changed lines, and "new violations only" merge gates possible without custom scripting.
- Build vs. buy for the last mile: PHP_CodeSniffer already detects violations; the only missing piece is the GitLab report serializer. This is a ~1 dev-day build, so the real decision is "own a 100-line report class forever" vs. "add a pinned dev dependency." The package is the cheaper answer unless you need a format it doesn't emit.
- Toolchain consolidation / roadmap: Forces an explicit answer to "is PHPCS our coding-standard tool of record?" If the answer is yes, this closes the loop from lint rule → CI signal → MR review → merge decision. If static analysis is moving to PHPStan/Psalm (both speak GitLab's format natively), this package's scope narrows to style only.
- Adoption metrics for engineering standards: Because output is structured JSON consumed by GitLab, you get trend lines — violation counts per MR, per directory, per severity — which is the raw material for "are we actually reducing legacy debt?" rather than a yes/no lint pass.
- Onboarding and review-experience investment: Shifts standards enforcement out of human code review and into automation, which is a concrete, defensible line item when arguing for reviewer time or for tightening rules on a legacy codebase (pair with baseline/ignore lists to avoid a flag day).
When to Consider This Package
Adopt when all of these hold:
- The repo is hosted on GitLab and MRs run GitLab CI/CD (self-managed or SaaS); the Code Quality widget is available on your tier.
- PHP_CodeSniffer is already in the dependency tree (or is the agreed standard), so this adds a report format, not a new tool.
- You want violations surfaced in the MR UI — particularly "only new violations block the merge" — rather than grepping CI logs.
- You are comfortable with a dev-only, single-maintainer, ~44-star dependency that is pinned and easy to replace.
Look elsewhere or reconsider when:
- GitHub / GitHub Actions is the platform — use
cs2pr-style annotation instead; this package's output is GitLab-specific.
- You need SARIF or multi-tool aggregation (PHPStan, Psalm, ESLint, Semgrep) in one report — prefer native GitLab formats (PHPStan has one) or a generic converter, and don't let one small package become your reporting layer.
- Your static analysis roadmap is moving off PHPCS; adding a PHPCS-specific integration now creates migration debt.
- You require vendor support, SLAs, or a security review of transitive deps — this will not clear that bar; budget for forking instead.
- Composer/plugin-path wiring is undesirable in your setup (e.g., heavily locked-down images, no ability to set PHPCS
installed_paths), since registration is the main integration friction.
How to Pitch It (Stakeholders)
For executives (one line): A small, free, dev-only add-on that turns our existing PHP lint results into GitLab merge-request quality reports — so standards are enforced by the pipeline instead of by reviewers, at roughly a day of setup and no runtime risk.
For engineering leadership: It closes the gap between "we have a coding standard" and "the standard is visible and enforceable at the point of review." Violations appear on the MR, new ones can be gated, and GitLab retains trend data we can use to show debt reduction. It is BSD-3 licensed, released as recently as Sept 2025, and is dev-dependency-only — zero production footprint, removable in an afternoon.
For the engineering team: Two-line install plus a --report=GitLab --report-file=gl-code-quality-report.json flag in the existing PHPCS job; no changes to application code, no new runtime services. Expect to spend the real effort on policy — which severities block, how legacy files are baselined — not on the integration.
Honest risk framing to include in the pitch: 44 stars and a narrow maintainer base means bus-factor risk. Mitigate by pinning the version, treating the report format as a replaceable adapter, and being willing to fork — the surface area is small enough that this is a genuine option, not a bluff. Position the package as a tactical enabler of a quality-gate decision, not as strategic infrastructure.