Alley Coding Standards Laravel Package

Product Decisions This Supports

• Quality-gate roadmap and CI enforcement. This release is a ruleset change, not a runtime feature: it adds a PHPCS sniff requiring type hints on the first parameter of filter callbacks. That directly supports the decision of how strict our automated code review is — each release like this is a ratchet in the definition of "done" for PHP work, and it belongs on the engineering-standards roadmap rather than the customer-facing one.
• Build vs. buy for coding standards. Adopting an externally maintained ruleset (Alley's) instead of hand-rolling and maintaining custom sniffs is a buy decision. Every incremental release like v2.5.0 is dividend on that choice — someone else is encoding WordPress-specific correctness rules so your team doesn't have to write or maintain them.
• Static analysis and type-safety investment. Filter callbacks in WordPress receive loosely-typed values (mixed at the boundary). Requiring type hints on the first parameter makes those boundaries explicit, which is a prerequisite for getting real value out of PHPStan/Psalm and for catching callback-signature mistakes (add_filter arity, priority args) before they hit staging. This informs whether we sequence static analysis adoption before or after standards adoption.
• Developer onboarding and review-load reduction. Automating this class of nit means reviewers stop commenting on callback signatures and spend review time on logic. Useful input to decisions about onboarding docs, pre-commit hooks, and whether to fund a "standards champion" rotation.
• Upgrade sequencing / tech-debt budgeting. A new sniff typically means new violations in existing code. This supports the decision of whether to adopt the rule repo-wide now (and absorb a cleanup sprint) or pin the previous version and adopt during the next planned refactor.

When to Consider This Package

Good fit when:

• The codebase is WordPress (plugin, theme, or VIP-scale platform) and you already run PHP_CodeSniffer in CI or pre-commit.
• You want an opinionated, maintained baseline rather than a bespoke ruleset, and you're comfortable with the maintainer's conventions (Alley's house style) becoming yours by default.
• You're standardizing across multiple repos or teams and need one installable, versionable source of truth for PHP style and correctness rules.
• You're layering toward static analysis and want the type-hint hygiene that makes PHPStan/Psalm tractable.

Look elsewhere when:

• You're not on WordPress — the value here is concentrated in WP-specific sniffs; WordPress-Coding-Standards, Slevomat-Coding-Standard, or a PHP-CS-Fixer setup may be a better primary.
• Your team has strong, differing conventions and no appetite for adopting someone else's house style wholesale — the friction will exceed the maintenance savings.
• You can't absorb a cleanup pass: each sniff addition is a potential CI failure on legacy code. If a red build blocks releases and there's no budget to remediate, pin the version and defer.
• You need rules for modern PHP frameworks (Laravel/Symfony idioms, strict PSR-12-only, PHP 8.3 features) that this ruleset does not target.
• Governance matters more than convenience — a single-vendor ruleset with a small maintainer group is a supply-chain and continuity consideration; check license, release cadence, and whether rules can be selectively disabled per-project.

Specifically for v2.5.0: it's a minor, additive rule. No breaking changes, no deprecations. It's safe to adopt, but expect new violations on existing filter callbacks — treat the upgrade as a small, schedulable cleanup item rather than a drop-in.

How to Pitch It (Stakeholders)

For executives: This is a free, externally maintained quality standard for our PHP/WordPress code, updated this week with a small but real addition — it now flags filter callbacks that omit parameter type hints. It costs us nothing to consume and reduces the amount of senior-engineer time spent on manual code review. Adopting it is a low-risk, low-cost lever on defect rates and onboarding speed, not a product feature; the trade-off is a modest one-time cleanup of existing code and a dependency we don't control.

For engineering leadership: v2.5.0 adds one sniff — type hints on the first parameter of filter callbacks. This is a quality ratchet: it improves the signal our static analysis can produce and removes a recurring review nit. Recommended path: bump the dev dependency, run the linter across the repo to size the violation count, and either fix inline (if small) or pin v2.4.1 with a dated cleanup ticket. No breaking changes, so the risk is confined to CI noise.

For engineers: New rule in the ruleset: filter callbacks need a typed first parameter. It's additive and disable-able per-line if a case is genuinely mixed. Practical benefit is better PHPStan/Psalm behavior at WordPress's untyped boundaries. Expect some existing callbacks to fail the build on upgrade — worth a single sweep rather than suppressing.