Laravel Stateless Session Laravel Package

Getting Started

The package solves one narrow problem: it exposes a csrf-header route that returns a fresh CSRF token in a response header so a JavaScript frontend can bootstrap Laravel’s CSRF protection without rendering a Blade form.

1. Install the package with Composer and let Laravel auto-discover the service provider.
2. Confirm the route is registered:

   php artisan route:list | grep csrf-header
   

3. Publish and inspect the package config if it ships one:

   php artisan vendor:publish --tag=csrf-header-config
   

   The key settings to look for are the route path, the header name (commonly X-CSRF-TOKEN), and the middleware stack applied to the route.
4. Make your first request:

   curl -i -c cookies.txt http://localhost/csrf-header
   

   You should see the token in the response header and any session cookie set by the web middleware group.

The first real use case is an SPA or Inertia app that needs to make state-changing requests. On app boot, fetch the token once, store it, and attach it to subsequent requests. The 1.1.0 release is relevant here because the new custom middleware support lets you put authentication, throttling, or tenancy checks in front of that token endpoint without forking the package.

Implementation Patterns

Axios bootstrap pattern. Fetch the token before the first mutating request and set it as a default header:

const { data, headers } = await axios.get('/csrf-header', {
  withCredentials: true,
});

axios.defaults.headers.common['X-CSRF-TOKEN'] =
  headers['x-csrf-token'];

If your client uses Laravel’s encrypted XSRF-TOKEN cookie convention, read the cookie instead and send it as X-XSRF-TOKEN. Pick one convention and use it consistently.

Custom middleware for the token route (new in 1.1.0). The package now lets you attach your own middleware to the csrf-header route. This is the main extension point for day-to-day use:

• Gate token issuance behind auth or auth:sanctum so anonymous clients cannot mint tokens.
• Add throttle:csrf-token to prevent token-endpoint hammering.
• Add tenant-resolution middleware when each tenant has its own session domain.
• Add audit logging if token issuance needs to be traceable.

Configure this through the package config’s middleware array, or by overriding the route definition if the package exposes that option. Keep session-related middleware (StartSession, ShareErrorsFromSession, etc.) ahead of your custom middleware if it reads or writes session state.

Authenticated token refresh. Issue a fresh token after login, logout, and role changes. A common pattern is to call the endpoint again after the auth state changes and replace the stored token. This avoids stale-token 419 responses after session regeneration.

Testing. Assert both the status and the header in feature tests:

$this->get('/csrf-header')
    ->assertOk()
    ->assertHeader('X-CSRF-TOKEN');

For middleware changes, add tests that assert unauthenticated requests are rejected and throttled requests return 429.

Route and config caching. If you deploy with route:cache and config:cache, add the token endpoint to your deployment smoke tests. Middleware and route-path changes made through config will not take effect until caches are rebuilt.

Gotchas and Tips

• Credentials must be sent. The token endpoint depends on the session cookie. Browser clients need withCredentials: true (Axios) or credentials: 'include' (fetch). Without it, the token will be issued against a different session or no session at all.
• CORS exposure. Cross-origin JavaScript cannot read a custom response header unless the server exposes it. Add Access-Control-Expose-Headers: X-CSRF-TOKEN to your CORS configuration, and allow credentials.
• Do not cache the response. A cached token can outlive its session. Add Cache-Control: no-store in your custom middleware or at the web server layer.
• Middleware order matters. Duplicating web middleware in the package config can start the session twice or produce inconsistent cookies. Prefer appending your middleware to the existing stack rather than replacing it.
• Token rotation. Laravel regenerates the session and CSRF token on login. Any token fetched before authentication is likely invalid afterwards. Refresh on auth transitions.
• Multiple tabs. Tokens are session-bound, so tabs generally share the same token. If you are rotating tokens aggressively, expect occasional 419s in older tabs; retry once on 419 rather than looping.
• Debugging checklist. Confirm the route appears in route:list, inspect the raw response headers with curl -i, verify the session driver is not array, check config:cache after config edits, and confirm the frontend is actually sending the header name the server expects.
• Extension points. Custom middleware is now the primary supported extension point. Use it for auth, throttling, CORS-adjacent headers, and auditing rather than modifying vendor files. Keep route and header names configurable so staging and production do not drift.