Auth Laravel Package

Getting Started

1. Install the package with Composer and publish its config:

   composer require <vendor>/<package>
   php artisan vendor:publish --tag=<package>-config
   

2. Register the guard/driver in config/auth.php and add the package middleware to your app/Http/Kernel.php or route group.
3. Configure the cache store used for token lookups. Since 3.3.2 the cache key is derived from a hash of the token, not from IP and device-id, so any shared cache store works consistently across nodes.
4. First place to look: the package config file, then your login controller/route. In 3.3.2 the login response includes the request token, so the quickest first use case is:
   • POST credentials to your login endpoint.
   • Read the token from the login response.
   • Call a protected route with Authorization: Bearer <token>.
5. Verify with php artisan route:list and a feature test that asserts a successful login returns a token and that a protected route returns 200 with the token and 401 without it.

Implementation Patterns

• Login-issued tokens: Return the request token directly from the login response (new in 3.3.2). This avoids a second token-issuance call and keeps the client flow to one request.
• Stateless authentication: Send the token as a Bearer header on every request. The package resolves the token from the request and validates it against the cache/token store.
• Cache by token hash: If you write custom cache logic—token revocation lists, warmup jobs, or lookup wrappers—key entries by the hash of the token, not by IP or device-id. This matches the package’s 3.3.2 behavior and works behind load balancers and mobile networks.
• Explicit TTLs: For tokens that should not expire, still set an explicit TTL in config or at issuance. The new “short TTL for token without expiry” behavior means a token created without an expiry will not live indefinitely.
• Custom middleware: Wrap the package guard in your own middleware when you need request logging, tenant scoping, or token metadata checks. Keep the package middleware as the authentication source of truth.
• Testing: Assert only the 401 status code, not the response body text. Since 3.3.2 no longer returns exception text on 401, tests that assert an error message will fail. Use assertStatus(401) and assert your own JSON envelope if you add one.
• Revocation workflows: Invalidate by token hash. After upgrading, clear the package’s cache namespace so stale keys from the old IP/device-id scheme do not linger.
• Backport awareness: 3.3.2 backports 4.3.2 behavior into the 3.x line. If you maintain multiple major versions, align config and tests with the 4.x behavior now to simplify future upgrades.

Gotchas and Tips

• Cache key change on upgrade: Existing cache entries were keyed by IP and device-id. After deploying 3.3.2 they will not be hit. Clear the relevant cache on deploy. If your cache was used for revocation, confirm old revocations are still enforced by your persistent store; otherwise re-revoke or clear and force re-authentication.
• No IP/device binding: Tokens are no longer implicitly tied to the originating IP or device-id. If your threat model relied on that binding, add your own claim or middleware check. Otherwise, accept that a stolen token is usable from any network until it expires or is revoked.
• Short TTL surprise: Clients that relied on non-expiring tokens will start seeing expiry. Set explicit TTLs and return expiry metadata in the login response so clients can refresh proactively.
• 401 without exception text: Unauthorized responses are now terse. Do not parse the body for diagnostics. Use application logs, the package’s log channel, or a custom exception renderer if you need a stable error code in the response.
• Token exposure in login response: Returning the token from login is convenient but increases exposure in logs and proxies. Ensure HTTPS, disable response-body logging on the login route, and consider HttpOnly cookies for browser clients.
• Cache store consistency: The token-hash cache key assumes all app nodes share the same cache store and hash algorithm. Avoid per-node file cache in multi-node deployments.
• Config quirks: Check the units for TTL settings and the cache TTL separately. A short default TTL for non-expiring tokens may be overridden in config; confirm the effective value in a test.
• Extension points: Use the package’s token repository, cache-key resolver, and exception renderer contracts rather than forking. These are the safest places to customize hash inputs, response shapes, and 401 payloads.
• Debugging 401s: Temporarily enable package debug logging or inspect the guard’s resolved user. Because the response no longer includes the exception message, reproduce failures in a feature test with withoutExceptionHandling() to see the underlying exception.