Session Lifecycle

Session Lifecycle

These methods wrap PHP's native session_*() functions behind the Manager, reachable through the facade (Session::start(...)). Each native call is guarded so failures surface as a SessionException rather than a bare warning.

start(array $options = []): bool

Registers your adapter (if you passed one to createImmutable()) and starts the session. $options are forwarded verbatim to session_start().

Session::createImmutable($adapter)
    ->start([
        'cookie_lifetime' => 3600,
        'cookie_secure'   => true,
        'cookie_samesite' => 'Lax',
    ]);

Call setName() / setID() before start() if you need them.

isStarted(): bool

True when a session is currently active (PHP_SESSION_ACTIVE).

if (!Session::isStarted()) {
    Session::start();
}

getName(): string and setName(string $name): Manager

Read or change the session name (the cookie name PHP uses). Set it before starting:

Session::setName('APPSESSID');
Session::start();

echo Session::getName(); // 'APPSESSID'

setName() returns the Manager, so lifecycle calls chain.

getID(): string and setID(string $id): bool

Read or set the session id. setID() returns whether the id was accepted, and must be called before start():

Session::setID($idFromSomewhere);
Session::start();

echo Session::getID();

getID() returns an empty string when there is no id yet.

regenerateId(bool $deleteOldSession = false): bool

Issues a fresh session id while keeping the current data. Call it after any privilege change — most importantly right after login — to defeat session fixation. Pass true to delete the old session record.

// after verifying credentials:
Session::regenerateId(true);
Session::set('user_id', $user->id);

See the Authentication recipe for the full pattern.

flush(): bool and unset(): bool

Clear all session variables while keeping the session open. flush() is an alias of unset(). Both require an active session and throw a SessionException otherwise:

Session::flush();
Session::all(); // []

// Without an active session:
Session::unset();
// SessionException: The session must be started for the "unset()" method to work.

destroy(): bool

Tears the session down entirely (session_destroy()):

Session::destroy();

A complete logout usually combines clearing data, regenerating the id, and destroying:

Session::flush();
Session::regenerateId(true);
Session::destroy();

Lifecycle at a glance

Method	Returns	Needs active session	Typical use
start	bool	—	Begin the session
isStarted	bool	—	Guard before starting
getName / setName	string / Manager	before start	Custom cookie name
getID / setID	string / bool	before start	Adopt an existing id
regenerateId	bool	✅	After login / privilege change
flush / unset	bool	✅ (throws otherwise)	Clear data, keep session
destroy	bool	✅	Logout / teardown

Next

• Reading & Writing Values
• Recipe: Authentication & Fixation
• Exceptions