Product Decisions This Supports
- Engineering standards consolidation (build vs. buy), now with a maintenance rider. v1.1.0 changes the calculus slightly: adopting this is still one Composer line, but the package now works by replacing faulty upstream CodeSniffer sniffs rather than by patching around them. That raises the true cost from "one line" to "one line plus a periodic compatibility chore every time PHPCS changes." Buy still wins, but budget it as an owned dependency you babysit, not a drive-by install.
- Documentation consistency at the codebase level. Unchanged in value: it mechanizes
bool vs boolean in docblocks and removes a recurring nitpick from human review. The rule's purpose is the same; only its implementation strategy moved.
- Toolchain upgrade planning (PHPCS v3 → v4). This release is a concrete data point for a real decision: when do we move the org's ruleset to CodeSniffer v4? The package now has a v4-shaped implementation path and presumably a v3 one — that compatibility claim is worth verifying and can be used as a canary for the wider ruleset migration.
- Roadmap framing: "standards hygiene" as a trackable workstream. Still a low-risk continuous-improvement slot with a measurable before/after (percentage of docblocks using long-form names). Add a second metric: number of PHPCS-version upgrade incidents attributable to third-party sniffs.
- Not a differentiator, and shouldn't be sold as one. No user-visible behavior change. Infrastructure debt prevention, budgeted in minutes plus a small recurring tax — not sprints.
When to Consider This Package
Adopt when:
- You already run PHPCS in CI with a shared, versioned ruleset across multiple repos — the marginal integration cost is a single rule reference.
- You have a real, measurable prevalence of long-form scalar names in comments (grep
@param boolean, @param integer, @var double); otherwise you're enforcing a rule that changes nothing.
- You maintain public packages or an SDK where docblock consistency is externally visible.
- Your team has already agreed on short names as the convention; this package enforces an existing decision rather than making one.
- You are on, or actively planning to move to, CodeSniffer v4 — this is now the strongest reason to pick it up, and the release note implies v4 support is the active development path.
Look elsewhere when:
- You don't run PHPCS, or you standardize exclusively on PHP-CS-Fixer — do not add a second linter for one rule.
- You need auto-fix. Still the single most important due-diligence item; unchanged by this release. If the sniff only reports, you've traded one manual chore for another.
- You pin to PHPCS v3 and have no near-term upgrade plan. v1.1.0's headline change is v4-internals-driven. If the new version assumes v4 behavior, or if its replacement sniffs behave differently under v3, you inherit risk for zero benefit. Stay on the previous version, pinned, until your PHPCS upgrade is scheduled.
- Maintenance risk matters to you — and this release makes that argument stronger. Two stars, near-zero dependents, single maintainer, and now a design that reaches into CodeSniffer internals and substitutes upstream sniffs. That means: it can silently shadow or conflict with other sniffs (including Slevomat/Doctrine replacements you already pull in), its behavior can drift on any PHPCS patch release, and the "vendor ~200 lines" fallback from the prior assessment is now understated — you'd be vendoring a fork that must track PHPCS internals, not a self-contained rule. Treat fork-and-vendor as a real but non-trivial contingency.
- A broader standard already covers it. Check Slevomat and Doctrine Coding Standard first; if you already pull one in, adding a micro-package that also overrides core sniffs increases both dependency count and conflict surface.
- You're a small team with no shared standards repo: coordination cost exceeds benefit.
New verification checklist before adopting v1.1.0: (a) does it declare and test against both PHPCS v3 and v4, or v4 only; (b) does it still offer a fixer; (c) does replacing faulty sniffs change reported behavior versus the previous version on your actual codebase — run both versions and diff the reports; (d) does it conflict with or duplicate sniffs in your current ruleset. Treat this minor version bump as potentially breaking, despite the semver number.
How to Pitch It (Stakeholders)
For executives: This is a tiny, zero-cost code-quality rule that keeps our documentation consistent. It installs in one line, runs automatically in CI, and removes a recurring class of nitpick from code review. No product behavior change, no runtime risk. Two caveats worth stating plainly. First, the new release reworks how the package hooks into our linter internals to stay compatible with the linter's next major version — so it is a dependency we now need to keep an eye on at each linter upgrade, not something we can install and forget. Second, it remains a low-adoption, single-maintainer package. Mitigation: pin the version, adopt the new release only alongside a planned linter upgrade, and keep the option of folding the logic into our own standards repository — though that fallback is now more work than a copy-paste. Recommendation: approve as routine standards maintenance, and schedule adoption with the PHPCS v4 migration rather than ahead of it.
For engineering: Add it to the shared ruleset and stop commenting on boolean vs bool in review. Deterministic, scoped to comments, trivially removable. Before merging v1.1.0: confirm which PHPCS majors it supports and that our pinned version matches; verify the fixer status (if report-only, run in report-only mode for two sprints and bulk-fix offenders); and diff the sniff report between the old and new versions on one representative repo, because v1.1.0 replaces upstream sniffs and could change output. Watch for overlap with Slevomat/Doctrine sniffs already in the ruleset. If any check fails, the fallback is a small custom sniff in our own standards package — more work than previously assessed, but fully under our control.