Laravel Stateless Session Laravel Package

Product Decisions This Supports

• Build vs. buy for cookie-less sessions: This package lets a Laravel app keep native session features (CSRF tokens, flash messages, validation error bags, multi-step form state, guest carts) while transporting the session via a response header instead of a cookie. That removes a recurring "should we write our own header-session bridge?" decision in favor of a small, single-purpose dependency.
• Client architecture for SPA and mobile: Directly supports the decision to run a first-party SPA or mobile app against a Laravel backend without third-party cookies — relevant as Safari ITP and Chrome's third-party cookie restrictions continue to erode cookie-based flows in embedded/cross-domain contexts.
• Session continuity as a product requirement: The 3.0.0 behavior — always return the session header, including on the first request and for missing/empty/undefined/0 inbound values, and return the final session ID after regeneration or invalidation — makes "session ID is a client-held resource" an explicit contract. This supports decisions about login/logout flows, token refresh, and analytics session stitching, and closes a class of confusing "my session disappeared after login" bugs.
• Roadmap gating: 3.0.0 requires Laravel 13.x and PHP 8.3+. Adopting it effectively schedules your framework and runtime upgrade. Treat it as a platform-migration workstream item, not an isolated Composer bump.
• Client SDK / interceptor design: Because clients must now retain the most recently returned session ID from every response — including rejected ones — this drives a concrete frontend decision: a single Axios/fetch interceptor that reads the exposed header and never swallows errors. The release's updated Axios example is directly reusable as the reference implementation.
• Operational/CORS decisions: The header must be surfaced cross-origin (Access-Control-Expose-Headers) and middleware registration differs under Laravel 13. This forces an explicit CORS and middleware-ordering decision that is easy to get wrong and hard to debug.
• Support and observability: Predictable session ID semantics after regeneration/invalidation reduce "session lost" support tickets and make request traces joinable across a session.

When to Consider This Package

Adopt when:

• You are on (or actively migrating to) Laravel 13 and PHP 8.3+.
• Your clients are first-party SPAs or native mobile apps that can set and read custom headers.
• You need Laravel-native session semantics (CSRF, flash, validation state, multi-step flows) but cannot or should not depend on cookies — cross-domain frontends, embedded/white-label UIs, or cookie-restricted browsers.
• You want a narrow, auditable dependency rather than bespoke middleware, and you value the added regression coverage (22 tests / 134 assertions across middleware execution, file-backed persistence, error responses, and session/header regressions) plus CI on PHP 8.3–8.5 with dependency audits.
• You are already on 2.x and are moving to Laravel 13 anyway — upgrade now rather than carrying an unsupported major.

Look elsewhere or defer when:

• You are staying on Laravel ≤12 or PHP <8.3 — 3.0.0 is a hard break; stay on 2.x (accepting lack of support) or defer.
• Your API is genuinely token-only (Sanctum/Passport bearer tokens with no server-side session state) — the package adds a concept you do not need.
• Server-side session storage is itself the architectural concern (horizontal scale, stateless edge/serverless deployment) — a signed token/JWT approach may fit better.
• Clients cannot control headers — plain HTML form posts, third-party iframes, or non-JS clients — where ordinary cookie sessions remain simpler.
• You depend on the prior undocumented behavior of not returning a session header on the first request or when no session exists. Audit any client that assumed "no header means new session" before upgrading; 3.0.0 changes that contract and can silently alter client state machines.

Upgrade prerequisites to verify: Laravel 13 middleware registration order, Access-Control-Expose-Headers for the session header, custom header-name configuration preserved, and a client release that persists the latest session ID from both success and error responses.

How to Pitch It (Stakeholders)

For executives: This is a small, single-purpose dependency that lets our Laravel backend keep first-class session features — CSRF protection, flash messages, form/validation state — without relying on browser cookies. That matters because cookie-based flows are increasingly unreliable for cross-domain SPAs and mobile clients. Release 3.0.0 is a maintenance and hardening release, not a feature investment: it aligns the package with Laravel 13 and PHP 8.3+, fixes incorrect session IDs after login/logout regeneration, removes broken install hooks, and adds meaningful automated test coverage and dependency auditing. Cost is low; the main work is sequencing, not engineering.

For engineering: 3.0.0 is a breaking major. It requires Laravel 13 and PHP 8.3+, drops Laravel 9 and older runtimes, and changes the header contract: the session header is returned on the first request and for missing/empty/undefined/0 inbound values, no session ID is exposed when no Laravel session is attached, and the final session ID is returned after regeneration or invalidation. Custom header names, cookie precedence, persistent data, and malformed-ID validation are preserved. Docs now cover Laravel 13 middleware registration, CORS exposure, and an Axios interceptor pattern that retains session IDs from both successful and rejected responses without swallowing errors. Composer's broken cghooks hooks are gone. Verification is stronger: 22 new tests / 134 assertions over real middleware execution, file-backed persistence, and error paths, with CI across PHP 8.3, 8.4, and 8.5, lowest secure dependencies, style checks, and audits.

Recommendation: Treat this as a coordinated backend + client release tied to the Laravel 13 migration. Read UPGRADE.md first, upgrade the application framework, then composer require overtrue/laravel-stateless-session:^3.0 --with-all-dependencies. Ship the client interceptor change in the same window — the new first-request and error-response header behavior changes what clients see, and staggered rollout is the primary risk here. If the Laravel 13 migration is not on the near-term roadmap, hold at 2.x and plan the move with the framework upgrade.