Filesystem Laravel Package

Getting Started

The v5.0.1 release is a patch on the 5.x line: it refines the wording of PSR-4 warnings emitted for Exception classes. There are no breaking changes, no new config keys, and no deprecations — the behavioral change is limited to the diagnostic message text.

Start here:

1. Confirm you are on 5.x. The improved warning text only exists from 5.0.1 onward. If you pinned ^5.0.0, a composer update is enough; there is no migration step.
2. Find where warnings surface in your workflow. The diagnostics are produced when the package maps namespaces to files (autoload resolution / class discovery). The first place to look after upgrading is whatever command, artisan task, or test suite currently emits the warnings in your project — run it once against an untouched branch and diff the output against what you saw on 5.0.0.
3. First use case: a single offending exception. Deliberately break one exception class — e.g. drop a file at app/Exceptions/Billing/ChargeFailedException.php while declaring namespace App\Exception\Billing; (singular Exception) — and run the check. The revised warning should now point at the namespace/path mismatch in terms a reviewer can act on, rather than a generic PSR-4 complaint.

The mental model to hold: this is a diagnostic surface, not a fixer. It tells you that a class's declared namespace and its file path disagree with the PSR-4 roots in composer.json. Your job is to reconcile the two, or to teach the tool about intentional exceptions.

Implementation Patterns

Treat warnings as a review artifact, not a build gate — initially. Roll the upgraded version out with warnings visible but non-blocking for one cycle. Exception classes are frequently the last thing a team cleans up, so a hard fail on day one tends to produce a mass-suppression commit that hides real problems.

Fix-forward in the same PR as the code that introduced the class. The highest-leverage pattern is local: developers see the improved warning the moment they add a new exception. Encourage running the check before pushing, so the mismatch never reaches CI. This is where the v5.0.1 wording improvement pays off — a clearer message means fewer "what does this even mean?" round trips.

Keep App\Exceptions (plural) consistent with the directory. The overwhelming majority of Laravel apps map App\ to app/, so app/Exceptions/FooException.php must declare namespace App\Exceptions;. Decide the singular/plural convention once, document it in the repo's contribution notes, and align any code generator or make:exception-style stub you use so new classes land correct by default.

Segment large exception namespaces by domain, mirroring the filesystem. For anything beyond a handful of classes, prefer app/Exceptions/Billing/ChargeFailedException.php → namespace App\Exceptions\Billing;. This keeps PSR-4 resolution trivially satisfied and gives the warning something precise to talk about when it does fire.

Wire it into CI as a reporting step with an explicit baseline. Run it on pull requests, publish the output as a build artifact or PR comment, and keep a checked-in allowlist for legacy offenders. Ratchet the allowlist down over time rather than adding to it — the allowlist should only ever shrink.

Pair it with composer dump-autoload -o in the pipeline. A stale autoloader can make a correct class look unreachable, which produces PSR-4 noise indistinguishable from a real namespace bug. Regenerating with optimized autoloading before the check eliminates that class of false positive.

Use it as an onboarding tool. New contributors are the most likely to place a file correctly but name the namespace from memory. Pointing them at the check on day one is cheaper than a review comment three days later.

Gotchas and Tips

The warning text changed — audit anything that parses it. This is the one genuinely actionable item in v5.0.1. If you grep logs for the old phrasing, match on it in a CI script, or assert on output in a test, those will silently stop matching. Search your repo for the previous message substring before rolling out. Prefer asserting on exit codes or a structured output mode (if the package exposes one) over message strings.

Case sensitivity bites on Linux only. App\Exceptions\BillingException and app/exceptions/BillingException.php resolve fine on a case-insensitive macOS volume and fail in CI. If a PSR-4 warning only appears in CI, suspect the directory casing first — the warning is telling the truth and your laptop is lying.

PSR-4 roots live in composer.json, not in the package config. When a warning seems wrong, read autoload and autoload-dev in composer.json before touching package settings. Two roots overlapping the same directory (e.g. App\ and App\Exceptions\ both mapped) is a common cause of confusing ambiguity.

autoload-dev classes are checked too. Test fixtures, fakes, and tests/-scoped exceptions can trip the warning. Either map them under a proper Tests\ root or exclude the directory — but be deliberate, because blanket-excluding tests/ also hides genuinely misplaced classes there.

Classes with no file at all. A namespace that exists only as a class-string reference (common with dynamically-resolved exception classes) has nothing to resolve. These produce warnings that look like path problems but are actually missing-file problems. Confirm the file exists before renaming anything.

Generated and vendored code should be excluded, not fixed. Anything under vendor/, plus build output, is out of your control. Exclude by path; don't attempt to rewrite namespaces in generated stubs you don't own.

Extension points are the escape hatch. If your project genuinely needs a namespace that doesn't map cleanly — a shimmed legacy tree during a migration, for instance — use the package's exclusion/allowlist mechanism rather than a custom fork. Keep those entries commented with an owner and a removal ticket; unowned exclusions are how a clean codebase quietly becomes a noisy one.

Debugging tip: reduce to one class. If the improved message still isn't clear, isolate — comment out every exception class except the suspect one, re-run, and read the warning in isolation. The new wording is more specific, but specificity is easier to read without twenty other lines around it.

Upgrade is safe. No config migration, no API changes, no deprecations introduced. The only work is the log/assertion audit above.