Session Management

Relevant source files

The following files were used as context for generating this wiki page:

• config/session.php
• config/auth.php
• database/migrations/0001_01_01_000000_create_users_table.php
• config/database.php
• phpunit.xml
• public/index.php

Session management in this framework provides a unified way to persist user data across multiple requests. It abstracts various storage backends—ranging from simple files and cookies to robust database and cache systems—allowing developers to switch between them via configuration without changing the application logic.

The system is tightly integrated with the authentication layer, where session-based "guards" manage user persistence. It handles the lifecycle of the session, including initialization during request handling, data encryption, and automated garbage collection through a lottery-based sweeping mechanism.

Sources: config/session.php:12-23, config/auth.php:41-45, public/index.php:21-25

Architecture and Drivers

The session architecture is driver-based, allowing for high flexibility in how data is stored. The default driver is determined by the SESSION_DRIVER environment variable, falling back to database if not specified.

Supported Drivers

The framework supports the following storage drivers:

• file: Stores sessions in storage/framework/sessions.
• cookie: Sessions are stored within encrypted, signed cookies.
• database: Stores sessions in a relational database table.
• memcached / redis / dynamodb: Leverages fast cache stores for session persistence.
• array: Used during testing to prevent data persistence between tests.

Sources: config/session.php:14-23, config/session.php:61, phpunit.xml:46

Data Flow Diagram

The following diagram illustrates how a request interacts with the session store:

The application bootstraps the session handler based on the configured driver to manage session data during the request lifecycle.
Sources: config/session.php:23, public/index.php:21-25

Configuration Options

Session behavior is highly customizable through the config/session.php file. Key parameters include lifetime, security settings, and cookie attributes.

Option	Type	Default	Description
driver	string	database	The storage engine used for sessions.
lifetime	integer	120	Minutes the session can remain idle before expiring.
expire_on_close	boolean	false	If true, sessions expire when the browser is closed.
encrypt	boolean	false	Whether session data should be encrypted before storage.
lottery	array	[2, 100]	Odds (2/100) of the session garbage collector running.
cookie	string	slug-session	The name of the cookie used to store the session ID.
path	string	/	The URL path where the cookie is available.
http_only	boolean	true	Prevents JavaScript access to the session cookie.
same_site	string	lax	Controls cross-site request cookie behavior.

Sources: config/session.php:23-189

Database Schema

When utilizing the database driver, sessions are stored in a dedicated table. This table tracks the session payload alongside metadata like user association and technical identifiers.

The session table links to the users table via user_id, allowing the application to track active sessions for specific users.
Sources: database/migrations/0001_01_01_000000_create_users_table.php:32-39

Security Implementation

The framework enforces several security measures to protect session data:

1. Encryption: When enabled, all session data is encrypted using the application's AES-256-CBC cipher and APP_KEY.
2. HttpOnly: By default, the http_only flag is set to true to mitigate Cross-Site Scripting (XSS) attacks.
3. SameSite Attribute: The same_site attribute is set to lax to provide a balance between usability and protection against Cross-Site Request Forgery (CSRF).
4. Secure Cookies: If SESSION_SECURE_COOKIE is enabled, cookies are only transmitted over HTTPS.

Sources: config/session.php:49-51, config/session.php:159-183, config/app.php:97-101

Integration with Authentication

Session management is the primary persistence mechanism for the default web authentication guard. When a user logs in, their identifier is stored in the session, which the session driver uses to retrieve the user instance on subsequent requests via the users provider.

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'users',
    ],
],

Sources: config/auth.php:41-45

Conclusion

Session management provides a robust and flexible system for maintaining state. By supporting multiple backends and providing sensible security defaults like HttpOnly cookies and CSRF protection (via SameSite), the system ensures that user data is handled efficiently and securely across various infrastructure environments.