Phpcs Psr4 Sniff Laravel Package

Product Decisions This Supports

• Enforcing PSR-4 compliance as a quality gate, not a convention. This package turns an implicit architectural standard into an automated, CI-enforceable check. For a PM, that means fewer "works on my machine" incidents, fewer autoload failures discovered in staging or production, and a measurable reduction in a class of defects that are cheap to prevent and expensive to diagnose.
• Build vs. buy (or rather, adopt vs. write). The team needs exactly one narrow check: does a class's fully qualified name match its file path under PSR-4? Writing and maintaining a custom PHP_CodeSniffer sniff has ongoing cost (PHPCS version compatibility, edge cases around multi-namespace roots, Composer PSR-4 vs PSR-0 mappings, test/psr-4-dev paths). At 27 stars and a single-purpose scope, this is a low-risk dependency that buys an afternoon of engineering time back and avoids owning bespoke tooling.
• Roadmap input on developer-experience and platform health work. If the codebase has accumulated autoload drift — common after large refactors, namespace renames, or splitting a monolith into packages — this sniff quantifies the problem and feeds a "tech debt paydown" or "CI hardening" initiative with concrete numbers (violation counts per directory) rather than vibes.
• Scoping a migration. When moving code into a new namespace, extracting a shared library, or converting a legacy directory to Composer autoloading, this sniff gives an objective definition of done: zero violations under the new root.
• Use cases well-suited to it: Laravel or Symfony apps with multiple PSR-4 roots; monorepos with many small packages; teams onboarding contractors who don't yet know the layout conventions; pre-acquisition or pre-audit code hygiene passes.
• What it does not support: runtime correctness, performance, security, or API design decisions. Do not let a green CI run from this sniff be presented as "our architecture is sound."

When to Consider This Package

Consider adoption when:

• The project has (or is moving to) PSR-4 autoloading with more than one namespace root — the case where humans most reliably get paths wrong.
• The team already runs PHP_CodeSniffer in CI, so this is an additive rule rather than a new toolchain.
• You want precise, actionable error messages in pull requests rather than opaque Class not found failures at runtime.
• You want to detect drift continuously during an in-flight refactor instead of discovering it at deploy time.
• You are comfortable pinning and occasionally bumping a small, single-maintainer dependency.

Look elsewhere, or handle differently, when:

• Maintenance risk matters more than convenience. Last release was June 2021. That is a long quiet period. Verify it works against your current PHP and PHPCS major versions before committing; if it does not, a few dozen lines of custom sniff code, or a Composer-based structural check in a test, may be the safer long-term home.
• You can solve it upstream for free. Composer's autoloader already fails loudly on PSR-4 mismatches when using optimized autoloading (composer dump-autoload -o) with strict PSR-4 checks, and static analyzers such as PHPStan and Psalm flag unresolvable classes. If the team already runs a strict static analysis baseline, this sniff may be redundant. Evaluate overlap before adding a rule.
• The team has no PHP_CodeSniffer footprint. Introducing PHPCS solely for one sniff means new config, new CI time, and a new baseline of pre-existing violations — likely a much larger project than intended.
• Very small or single-root projects, where the path-to-class relationship is trivially obvious and drift is rare.
• You need broad, opinionated style enforcement. This is deliberately narrow. Pair it with a coding-standard ruleset rather than expecting it to be one.

How to Pitch It (Stakeholders)

To executives: This is a small, free, open-source add-on to a tool our engineers already use. It automatically blocks a specific category of mistake — code files whose location doesn't match their declared namespace — before it reaches production. Those mistakes cause autoload failures that are confusing to debug and occasionally cause outages on deploy. Cost is negligible: a config line and a few hours of setup. The main caveat is that the project hasn't been updated since 2021, so engineering will validate compatibility first. Frame it as cheap insurance on deployment reliability, not a strategic investment.

To engineering: We add one PHP_CodeSniffer sniff that enforces PSR-4 path/namespace agreement across all our autoload roots. It's a small, single-purpose package — worth adopting instead of maintaining a homegrown sniff, but we should confirm PHPCS compatibility given the 2021 last release, and we should decide whether our existing static analysis already covers this. Expect a one-time triage of pre-existing violations before we can flip it to blocking; run it in report-only mode on the current branch first so the diff doesn't land as noise in an unrelated pull request.