Scoped Auth Laravel Package

Getting Started

• Install with composer require mpyw/scoped-auth. v2.1.1 is a compatibility/maintenance release, so there are no new setup steps compared with v2.1.0.
• Start with the package README’s basic usage section, then review the Fortify integration docs referenced in the release notes. If you use Fortify, ensure you are on laravel/fortify >= 1.33.0 for the documented fix.
• Confirm your config/auth.php guards/providers before writing application code. The package is most useful when you need more than one authentication context in the same app, such as web for customers and a separate admin scope for staff.
• First practical use case: put an admin route group behind the scoped guard/middleware while leaving public/customer routes on the default web guard. Log in through both scopes in the same browser session and verify that each scope resolves its own user independently.
• Run php artisan route:list, then exercise login, logout, and “remember me” behavior for each scope. This quickly exposes session-key or middleware-order mistakes.

Implementation Patterns

• Keep scope usage explicit. Prefer a scoped helper/facade or $request->user('admin') over the global Auth::user() when a route can be reached by multiple user types.
• Group routes by scope and apply scope-specific middleware at the group level. Avoid relying on the default auth middleware alone in multi-scope areas.
• In controllers, resolve the scoped user once at the start of the action and pass it into services/policies. This keeps authorization decisions tied to the intended scope rather than the default guard.
• In Blade, use scope-aware checks for navigation and layout switching. A global @auth check is usually too broad when customer and admin sessions can coexist.
• For Fortify integration, follow the updated documentation closely and keep Fortify at a version that includes the v1.33.0 fix. Use distinct route prefixes/guards per authentication context rather than trying to overload a single login flow.
• In tests, use actingAs($user, 'admin') or the package’s equivalent scope-aware helper, and assert that logging out of one scope does not affect the other. Cover both scopes in feature tests, not just unit tests.
• When integrating policies/gates, ensure the correct scoped user is passed in. If you use middleware to set a “current scope,” make that scope available to downstream authorization code explicitly.
• Treat v2.1.1 as a safe compatibility upgrade: it adds PHP 8.5 CI coverage, updates Fortify documentation, and adds Laravel 14 support. There are no documented breaking changes or new features, so no application refactor should be required.

Gotchas and Tips

• The most common failure mode is accidentally using the default guard when the request is in a non-default scope. Audit controllers, middleware, Blade templates, and event listeners for bare Auth::user()/auth()->user() calls.
• Verify session isolation between scopes. Logging out of one scope should not clear the other; test with your actual session driver and cookie configuration, not just the array driver.
• Middleware order matters. Ensure session startup and authentication middleware run before your scope resolution middleware, and avoid caching authenticated responses without varying the cache key by scope.
• If you use Fortify, pin a compatible version and re-read the integration docs after upgrading. The v2.1.1 release specifically references a Fortify issue fixed in v1.33.0.
• Laravel 14 support is CI-covered in v2.1.1, but check the package’s Composer constraints against your exact Laravel/PHP versions. PHP 8.5 is now in the CI matrix; older PHP versions may still work but are not the focus of this release.
• After changing guard or package config, run php artisan config:clear. Stale config is a frequent source of “wrong user” bugs in multi-guard applications.
• For debugging, inspect the active guard with Auth::guard('admin')->check() and compare it with Auth::user(). Also inspect session keys when logout behavior looks inconsistent.
• Use the package’s extension points/config only where necessary. Avoid overriding internals; keep custom behavior in your own guards, middleware, or service bindings so future compatibility releases remain low-risk.