Session Laravel Package

Getting Started

This package is a read-only split of the main marko-php/marko monorepo, so treat it as the low-level session contract layer, not a standalone product. Your first move is to add it alongside the framework:

composer require marko/session

Then look at the interfaces in src/ — you are meant to code against SessionInterface (and any related driver/handler contracts) rather than a concrete implementation. If you need docs, examples, or support, go to the parent repo at https://github.com/marko-php/marko; issues and PRs must be opened there, since this split repo accepts neither.

The first real use case is straightforward request-scoped state: registering the session as a service, opening it during the request lifecycle, and reading/writing values in a controller or handler:

$session->set('cart_id', $cartId);
$cartId = $session->get('cart_id', default: null);

Get that round-trip working (write in one request, read in the next) before layering on authentication, flash messages, or CSRF — those are all built on the same primitives and will hide any wiring mistakes you make in the basic setup.

Implementation Patterns

Register a concrete driver, depend on the interface. In day-to-day code, inject SessionInterface into handlers and services and let the framework's service container bind the concrete session (native PHP, file, array, etc.). This is what makes the package useful — swapping test doubles for production storage is a binding change, not a code change.

Open/close at the edges. Treat session start/close as middleware, not as something scattered through business logic. Read session data at the top of the request, mutate it intentionally, and let the middleware commit and emit the cookie. Handlers should receive already-populated state.

Flash messages on top of get/set. The common pattern is a two-key trick: write to _flash.new, and on each request rotate new → old and drop the previous old:

$session->set('_flash.new', ['status' => 'Saved']);
// next request: old values are readable, then cleared
$messages = $session->get('_flash.old', []);

Regenerate on privilege change. On login, logout, or any role escalation, call regenerate() (or whatever the contract exposes) so the session ID changes but data survives. This is the single most important security pattern and the easiest to forget.

CSRF tokens as session state. Generate a random token once, store it in the session, and compare it against a hidden form field on submit. Since the session already carries a per-visitor ID, this is a natural fit — no extra storage needed.

Testing with a fake session. Bind an in-memory/array session implementation in your test container so handlers can be exercised without touching cookies or $_SESSION. Assert on get() after the handler runs rather than reaching into globals.

Integration boundary. Sessions sit between your HTTP layer (cookie parsing/emission) and your domain layer. Keep cookie configuration — name, domain, path, Secure, HttpOnly, SameSite — in config, and keep domain code free of any knowledge of how the session is persisted.

Gotchas and Tips

"Headers already sent." Any output before the session opens or writes will break cookie emission. Open the session in middleware before rendering, and never echo/var_dump in bootstrap code while debugging session issues — you will cause the very failure you are chasing.

Read-only repo confusion. Composer will happily install it, but if you find a bug, a PR against marko-php/marko-session will be closed. Open it against marko-php/marko instead. Pin a version in composer.json and watch the monorepo's release notes, since this split has essentially no independent activity (0 stars, 0 dependents) and will not self-document.

session_start() collisions. If native PHP sessions are the underlying driver, calling session_start() yourself, or having a legacy script do it, produces warnings and undefined behavior. Route all session access through the package's interface so the lifecycle is owned in one place.

Cookie flags in development vs. production. Secure and strict SameSite will silently prevent cookies from being set over plain HTTP on localhost, which reads as "the session doesn't persist." Make these configurable per environment and verify with browser devtools that Set-Cookie actually appears in the response.

Session fixation and ID reuse. Regenerating the ID is not optional. Also be explicit about whether regenerate() destroys old data — the safe default is to preserve data but destroy the old ID, and you should test that the old ID is rejected afterward.

Serialization constraints. Session storage may serialize values, so avoid storing closures, resources, or large object graphs. Store IDs and re-fetch from the database; this also avoids stale-data bugs when two requests touch the same record.

Concurrency. File-based or native sessions lock per-session; long-running requests holding the session open will block parallel AJAX calls from the same browser. Close the session early (or use a driver that doesn't lock) for requests that only need to read once.

Testing hygiene. Sessions leak between tests if the underlying storage is global. Reset the session store in setUp()/tearDown(), and prefer a fresh in-memory implementation per test rather than clearing $_SESSION by hand.

Extension points. The interfaces are the extension surface: implement your own driver (Redis, database, encrypted cookie store) behind the same contract and bind it in the container. That is the intended way to add capability — there is no plugin system beyond this, and given the package's zero-star, zero-dependent status, expect to own any customization rather than relying on a community ecosystem.