Phpcsutils Laravel Package

Product Decisions This Supports

• Build vs. buy for custom coding standards. If we are maintaining an internal PHPCS standard (house style rules, framework conventions, deprecation/migration rules), PHPCSUtils shifts the "build" cost down: it supplies token-group constants, abstract sniff base classes, and utility functions (array splitting, list() assignment targets, DocBlock detection, etc.) that we would otherwise reimplement per sniff. That is a direct reduction in engineering hours and in bespoke code we own.
• Roadmap sequencing for the static-analysis workstream. Because it is tested against PHPCS 3.13.5 through 4.x and backports the latest PHPCS native utilities, it lets us target PHPCS 4.x without forcing our users/CI to upgrade immediately. That de-risks a "PHPCS 4 readiness" roadmap item we would otherwise have to schedule as a hard cutover.
• Platform decision: do we ship a reusable standard, or one-off scripts? PHPCSUtils is only valuable if we intend to own and evolve sniffs. Its existence lowers the threshold at which "maintain a first-class standard" beats "throw a script in CI," which is a strategic call about how much we invest in automated code quality.
• Deprecation/migration tooling. The utility layer makes it cheap to write sniffs that flag internal API misuse or removed patterns — a candidate feature for reducing framework upgrade support load.
• Extensibility and partner/community story. If we open-source our standard or accept contributed sniffs, using the de-facto utility layer lowers the bar for outside contributors and reduces review overhead.
• Dependency and licensing strategy. Choosing it as a transitive dependency of our standard (rather than an end-user-facing product) settles a packaging question: we inherit LGPL-3.0 obligations and must ship install guidance and a friendly "not installed" rule-ref, which is a support-cost line item to budget.
• Not a decision this supports: selecting what to lint, or comparing static analysis vendors. It is sniff-authoring infrastructure, not an analysis engine — it does no checking on its own.

When to Consider This Package

Adopt when:

• We author or maintain sniffs, or plan to — not merely consume an off-the-shelf standard.
• Our standard is Composer-distributed and PHP-only; the bundled Composer PHPCS plugin removes manual installed_paths registration, which is a real onboarding-friction win.
• We want one codebase supporting a wide PHPCS version range (3.13.5+ through 4.x) and a wide PHP/PHPUnit range (PHP 5.4–8.5, PHPUnit 4–11 for its test utilities), typically because our users' environments are heterogeneous.
• We test our sniffs and want the provided UtilityMethodTestCase and abstract base classes instead of building harness code.
• We accept UTF-8-only source files (its stated support boundary) and do not need JS/CSS sniffing.

Look elsewhere / do not adopt when:

• We only consume an existing standard; PHPCSUtils buys us nothing directly — it is plumbing for standard authors.
• LGPL-3.0 is a blocker for legal or distribution reasons. Even if dynamically consumed via Composer, this needs an explicit review; do not let engineering decide silently.
• We need JS/CSS linting support — explicitly unsupported and being dropped with PHPCS 4.x.
• We need non-UTF-8 file encodings.
• We want a commercial SLA, vendor accountability, or a large independent user base. Signals here are thin: 63 stars and effectively no listed dependents. Counter-evidence is that it lives under the PHPCSStandards org with docs, changelog, CI, coverage, and releases, and is the utility layer the wider PHPCS standard ecosystem is built on — so the low star count is a popularity artifact, not a quality verdict.
• We are actually solving "find bugs in PHP" rather than "enforce a style/convention." PHPStan, Psalm, or Rector are the right product category; PHPCSUtils would be a category error.
• Our PHPCS baseline is below 3.13.x, or we cannot adopt the required Composer plugin permissions (allow-plugins), which introduces a known end-user friction point.

Recommended next step: a timeboxed spike — port one representative sniff to PHPCSUtils and measure lines removed, then run legal review on LGPL obligations and confirm the release cadence is adequate for our maintenance window.

How to Pitch It (Stakeholders)

For executives: We are deciding whether to build our PHP coding-standard rules on a shared utility library instead of from scratch. The library is free, LGPL-licensed, actively released, and is the utility layer the PHP_CodeSniffer standards ecosystem is built on. It does not add a new product surface — it reduces the cost and risk of something we already need: consistent, automated enforcement of our code conventions. The main upside is engineering leverage and PHPCS 4.x readiness; the main risks are the LGPL licence (needs a legal sign-off, not an engineering call) and its low public visibility, which we judge as a popularity artifact rather than a quality signal given the active maintenance, documentation, and ecosystem reliance. Ask: approve a short spike plus legal review, not a full commitment.

For engineering: This is not a linter and it does nothing on its own — it is a toolkit for people writing sniffs. You get token-group constants, abstract sniff classes that do the boilerplate, utility functions for the parsing edge cases we keep rewriting badly (arrays, list() targets, DocBlocks), and a test case base class supporting PHPUnit 4–11. It backports current PHPCS native utilities so we can write against one API and stay compatible from PHPCS 3.13.5 through 4.x instead of pinning our users. Integration is a single Composer require plus allowing the dealerdirect plugin; non-Composer installs need a documented extra path registration and a PHPCSUtils_DIR bootstrap tweak for tests. Constraints to design around: UTF-8 files only, no JS/CSS support, PHP 5.4 floor. Add <rule ref="PHPCSUtils"/> to our ruleset so a missing install surfaces as a clear error rather than a fatal class-not-found.