Session / $session

$session->get($key) or $session->$key

Get a session variable.

• Arguments: get(string|object $key, string $_key = null)
• Returns: mixed — value, or null if not set
• Pass a namespace as the first argument and a key as the second to read a namespaced value (see Namespaced values below).

// Set a session variable
$session->set('firstName', 'Bob');

// Get it back (current or any future request)
$name = $session->get('firstName'); // "Bob"

// Property-style access is also supported
$session->firstName = 'Bob';
$name = $session->firstName;

$session->getVal($key)

Get a session variable, with a fallback value when not present. Available 3.0.133.

• Arguments: getVal(string $key, mixed $val = null)
• Returns: mixed — the session value, or $val if not found

// Returns "guest" if 'userName' is not in the session
$name = $session->getVal('userName', 'guest');

$session->getAll()

Get all session variables as an associative array.

• Arguments: getAll(string|object $ns = null)
• Returns: array

$vars = $session->getAll();
foreach($vars as $key => $value) {
    echo "$key: $value\n";
}

$session->set($key, $value) or $session->$key = $value;

Set a session variable.

• Arguments: set(string|object $key, mixed $value, mixed $_value = null)
• Returns: $this
• To write a namespaced value: pass a namespace as the first argument, a key as the second, and the value as the third.

$session->set('userName', 'bob');
$session->userName = 'bob'; // property-style equivalent

// Chaining is supported
$session->set('a', 1)->set('b', 2);

$session->remove($key)

Remove a session variable.

• Arguments: remove(string|object $key, string|bool $_key = null)
• Returns: $this

// Remove a single variable
$session->remove('firstName');

// Remove a single variable in a namespace
$session->remove('my_namespace', 'firstName');

// Remove all variables in a namespace
$session->remove('my_namespace', true);

$session implements IteratorAggregate, so you can iterate all non-namespaced session variables with foreach:

foreach($session as $key => $value) {
    echo "<li>$key: $value</li>";
}

$session->login($name, $pass)

Log in a user by name and password.

• Arguments: login(string|User $name, string $pass, bool $force = false)
• Returns: User|null — the logged-in User on success, null on failure
• Automatically sets the current user on success.
• Specify $force = true to skip password check (or use forceLogin() instead).

$user = $session->login('bob', 's3cr3t');

if($user) {
    $session->redirect('/dashboard/');
} else {
    echo "Invalid username or password.";
}

$session->logout()

Log out the current user and clear all session variables.

• Arguments: logout(bool $startNew = true)
• Returns: $this
• Passing false for $startNew skips starting a new session after logout.

$session->logout();
$session->redirect('/login/');

$session->forceLogin($user)

Log in a user without requiring a password. Useful for admin tools, programmatic user-switching, etc.

• Arguments: forceLogin(string|User $user)
• Returns: User|null

$user = $session->forceLogin('bob');

$session->getIP()

Get the IP address of the current user.

• Arguments: getIP(bool $int = false, bool|int $useClient = false, int $numParts = 0)
• Returns: string|int

$ip = $session->getIP();            // "1.2.3.4" or IPv6 string
$n  = $session->getIP(true);        // as integer (crc32 for IPv6)

// Use X-Forwarded-For / HTTP_CLIENT_IP (useful behind a proxy)
$ip = $session->getIP(false, true);

// Partial IP for privacy-preserving logging 3.0.258+
$ip = $session->getIP(false, false, 3);  // "1.2.3" (first 3 octets)
$ip = $session->getIP(false, false, 2);  // "1.2"

• If running behind a load balancer or reverse proxy, use $useClient = true to read the forwarded IP. Be aware this header can be spoofed.
• IP-based session fingerprinting is unreliable on mobile networks (carrier-grade NAT) and cellular connections where IPs change between towers.

$session->hasCookie()

Check whether a session cookie is present.

• Arguments: hasCookie(bool $checkLogin = false)
• Returns: bool
• Pass true to check for the challenge cookie instead (indicates login may be active).

if($session->hasCookie()) {
    // session cookie is present
}

$session->hasLoginCookie()

Check whether a login challenge cookie is present, indicating the user was logged in at some point. Does not verify that the session is currently valid.

• Returns: bool
• Available 3.0.175. Equivalent to hasCookie(true).

if($session->hasLoginCookie()) {
    // likely a logged-in or recently logged-in user
}

$session->getHistory()

Get the session history (previous URLs visited). Requires $config->sessionHistory > 0. Each entry is an array with url, page (ID), and time (unix timestamp) keys.

• Returns: array

$history = $session->getHistory();
foreach($history as $entry) {
    echo $entry['time'] . ': ' . $entry['url'] . "\n";
}

$session->close()

Close the session early, releasing the session lock. Useful for long-running requests (sitemap generation, exports, etc.) that don't need to read or write session data, so the user can navigate other pages concurrently.

$session->close();
// ... long-running render follows

• Session variables set via $session are stored in a dedicated namespace within $_SESSION — they do not appear in a plain $_SESSION read and vice versa.
• Values must be serializable PHP types (strings, numbers, arrays). Objects are not recommended unless they are fully serializable.
• To persist non-user data across requests independently of the session lifecycle, and independent of any specific sessions, use $page->meta() (page-scoped) or $cache (global).
• Source file: wire/core/Session/Session.php.