Auth Laravel Package

Getting Started

Start by installing the package via Composer (composer require spiral/auth) and enabling the Spiral\Auth\AuthCompiler and Spiral\Auth\AuthMiddleware in your Spiral application’s kernel config (app.php). Next, implement the Spiral\Auth\UserProviderInterface for your domain model (e.g., a database-backed UserProvider). Register it as a shared service and configure the auth component in config/auth.php to reference your provider and specify guard (e.g., web or api). Your first use case: protect a route by injecting the Spiral\Auth\AuthGuardInterface in your controller action and calling $guard->check() before processing sensitive logic.

Implementation Patterns

• Guard-based authentication: Inject AuthGuardInterface to verify credentials or session state per-request. Use different guards (e.g., web, api) for frontend vs. API auth flows.
• Custom user providers: Implement UserProviderInterface for diverse sources (DB, LDAP, JWT, Redis). The provider handles user loading, password verification (verifyPassword()), and token refresh if applicable.
• Middleware chaining: Use AuthMiddleware in route groups to enforce auth before action execution. Customize guards or redirect URLs via config or request attributes (setGuard(), setRedirect()).
• Stateless vs. stateful: For APIs, pair with stateless guards and JWT/tokens; for web apps, combine with Spiral’s session support. The component abstracts session handling via the Spiral\Auth\State interface.
• Authorization hooks: Integrate with spiral/access-control or custom logic via the Spiral\Auth\Event\AuthenticationSuccess or AuthenticationFailure events for logging or audit trails.

Gotchas and Tips

• Legacy support: The last release is from 2019—ensure compatibility with modern Spiral (v2+); you may need to backport or patch against breaking changes in core interfaces.
• Password hashing: The package does not handle hashing; implement it manually in your UserProvider using password_verify() and password_hash()—forgot this and auth breaks silently.
• Guard name mismatch: The default guard name (auth in early versions vs. web/api in config) can cause "no guard" exceptions—double-check config/auth.php → guards key matches your injection or middleware config.
• Extensibility point: Extend Spiral\Auth\Guard for complex flows (e.g., 2FA), but avoid deep inheritance—favor composition by swapping UserProvider or implementing Spiral\Auth\TokenProviderInterface.
• Debugging: Use Spiral\Auth\AuthGuardInterface::getLastLoginError() and enable logging in middleware via AuthLoggerInterface. Clear logs with php app.php cache:clear auth since config caching is aggressive.
• Token refresh: If using stateful auth, ensure AuthState::refresh() is called after user identity change (e.g., password update) to prevent stale session issues.