A PHP session normally uses a cookie to connect the browser to server-side data.

The browser stores the session cookie. The server stores the session data. On each request, the browser sends the cookie back, and PHP uses the cookie value as the session ID.

¶Session cookie name

The cookie name is controlled by the name config value.

$session = new Session($handler, [
	"name" => "GT",
]);

If no name is supplied, the library uses PHP’s familiar PHPSESSID default.

[!NOTE] WebEngine’s default session name is GT. In a WebEngine project this is configured in the [session] section of config.ini.

¶Cookie lifetime

cookie_lifetime controls how long the browser should keep the session cookie.

$session = new Session($handler, [
	"cookie_lifetime" => 3600,
]);

The library default is 0, which means a browser-session cookie. Browsers normally clear session cookies when the browser session ends.

This does not make session data permanent. Session data should still be treated as temporary. If we need to remember something important, store it in a database or another durable system.

¶Secure and HTTP-only cookies

The defaults are:

• cookie_secure: true
• cookie_httponly: true

cookie_secure tells the browser to send the cookie only over HTTPS.

cookie_httponly prevents JavaScript from reading the cookie through document.cookie.

For a production site, these are good defaults. During local development over plain HTTP, we may need to set cookie_secure to false.

¶SameSite

The default SameSite policy is Lax.

$session = new Session($handler, [
	"cookie_samesite" => "Lax",
]);

Lax is a practical default because it protects against many cross-site request patterns while still allowing normal navigation from another site to ours.

¶Cookie-only sessions

The defaults are:

• use_only_cookies: true
• use_cookies: true
• use_trans_sid: false

That means the session ID should be carried in a cookie, not added to URLs.

If use_trans_sid is enabled and cookies are disabled, the library can read the session ID from the request query data using the configured session name. This mode is rarely needed for modern applications.

¶Strict mode

use_strict_mode defaults to true.

Strict mode tells PHP not to accept uninitialised session IDs supplied by a client. This helps avoid session fixation problems.

¶Ending a session

Session::kill() asks the handler to destroy the current session data and sends an expired cookie for the current session name.

$session->kill();

This is useful during logout. Application code should also remove any user-specific state it stores outside the session.

---

Next, choose where session data is stored in Storage handlers.