WooCommerce Code Reference

WC_Session_Handler extends WC_Session
in package

Session handler class.

Table of Contents

$_cookie  : string
Cookie name used for the session.
$_customer_id  : string|null
Customer ID.
$_data  : array<string|int, mixed>
Session Data.
$_dirty  : bool
Dirty when the session needs saving.
$_has_cookie  : bool
True when the cookie exists.
$_session_expiration  : int
Stores session due to expire timestamp.
$_session_expiring  : int
Stores session expiry.
$_table  : string
Table name for session data.
__construct()  : mixed
Constructor for the session class.
__get()  : mixed
Magic get method.
__isset()  : bool
Magic isset method.
__set()  : mixed
Magic set method.
__unset()  : mixed
Magic unset method.
cleanup_sessions()  : mixed
Cleanup session data from the database and clear caches.
delete_session()  : mixed
Delete the session from the cache and database.
destroy_session()  : mixed
Destroy all session data.
forget_session()  : mixed
Forget all session data without destroying it.
generate_customer_id()  : string
Generate a unique customer ID for guests, or return user ID if logged in.
get()  : mixed
Get a session variable.
get_customer_id()  : string
Get customer ID. If the session is not initialized, returns an empty string.
get_customer_unique_id()  : string
Get session unique ID for requests if session is initialized or user ID if logged in.
get_session()  : mixed
Returns the session.
get_session_cookie()  : bool|array<string|int, mixed>
Get the session cookie, if set. Otherwise return false.
get_session_data()  : array<string|int, mixed>
Get session data.
has_session()  : bool
Return true if the current user has an active session, i.e. a cookie to retrieve values.
init()  : mixed
Init hooks and session data.
init_session_cookie()  : mixed
Setup cookie and customer ID.
maybe_set_customer_session_cookie()  : mixed
Hooks into the wp action to maybe set the session cookie if the user is on a certain page e.g. a checkout endpoint.
maybe_update_nonce_user_logged_out()  : int|string
When a user is logged out, ensure they have a unique nonce to manage cart and more using the customer/session ID.
save_data()  : mixed
Save data and delete guest session.
set()  : mixed
Set a session variable.
set_customer_session_cookie()  : mixed
Sets the session cookie on-demand (usually after adding an item to the cart).
set_session_expiration()  : mixed
Set session expiration.
update_session_timestamp()  : mixed
Update the session expiry timestamp.
init_hooks()  : mixed
Initialize the hooks.
use_secure_cookie()  : bool
Should the session cookie be secure?
clone_session_data()  : mixed
Clones a session to the current session. Exclude customer details for privacy reasons.
get_cache_prefix()  : string
Gets a cache prefix. This is used in session names so the entire cache can be invalidated with 1 function call.
hash()  : string
Hash a value using wp_fast_hash (from WP 6.8 onwards).
init_session()  : mixed
Initialize the session from either the request or the cookie.
init_session_from_request()  : bool
Initialize the session from the query string parameter.
is_customer_guest()  : bool
Checks if this is an auto-generated customer ID.
is_session_cookie_valid()  : bool
Checks if session cookie is expired, or belongs to a logged out user.
is_session_expiring()  : bool
Checks if the session is expiring.
migrate_guest_session_to_user_session()  : mixed
Migrates a guest session to the current user session.
restore_session_data()  : mixed
Restore the session data from the database.
session_exists()  : bool
Check if a session exists in the database.
verify_hash()  : bool
Verify a hash using wp_verify_fast_hash (from WP 6.8 onwards).

Properties

Methods

__set()

Magic set method.

public __set(string $key, mixed $value) : mixed
Parameters
$key : string

Key to set.

$value : mixed

Value to set.

Return values
mixed —

delete_session()

Delete the session from the cache and database.

public delete_session(string $customer_id) : mixed
Parameters
$customer_id : string

Customer session ID.

Return values
mixed —

generate_customer_id()

Generate a unique customer ID for guests, or return user ID if logged in.

public generate_customer_id() : string
Return values
string —

get()

Get a session variable.

public get(string $key[, mixed $default_value = null ]) : mixed
Parameters
$key : string

Key to get.

$default_value : mixed = null

used if the session variable isn't set.

Return values
mixed — value of session variable

get_customer_unique_id()

Get session unique ID for requests if session is initialized or user ID if logged in.

public get_customer_unique_id() : string

Introduced to help with unit tests.

Tags
since
5.3.0
Return values
string —

get_session()

Returns the session.

public get_session(string $customer_id[, mixed $default_value = false ]) : mixed
Parameters
$customer_id : string

Customer ID.

$default_value : mixed = false

Default session value.

Return values
mixed — Returns either the session data or the default value. Returns false if WP setup is in progress.

get_session_cookie()

Get the session cookie, if set. Otherwise return false.

public get_session_cookie() : bool|array<string|int, mixed>

Session cookies without a customer ID are invalid.

Return values
bool|array<string|int, mixed> —

has_session()

Return true if the current user has an active session, i.e. a cookie to retrieve values.

public has_session() : bool
Return values
bool —

maybe_set_customer_session_cookie()

Hooks into the wp action to maybe set the session cookie if the user is on a certain page e.g. a checkout endpoint.

public maybe_set_customer_session_cookie() : mixed

Certain gateways may rely on sessions and this ensures a session is present even if the customer does not have a cart.

Return values
mixed —

maybe_update_nonce_user_logged_out()

When a user is logged out, ensure they have a unique nonce to manage cart and more using the customer/session ID.

public maybe_update_nonce_user_logged_out(int $uid, int|string $action) : int|string

This filter runs everything wp_verify_nonce() and wp_create_nonce() gets called.

Parameters
$uid : int

User ID.

$action : int|string

The nonce action.

Tags
since
5.3.0
Return values
int|string —

save_data()

Save data and delete guest session.

public save_data([string|mixed $old_session_key = '' ]) : mixed
Parameters
$old_session_key : string|mixed = ''

Optional session ID prior to user log-in. If $old_session_key is not tied to a user, the session will be deleted with the assumption that it was migrated to the current session being saved.

Return values
mixed —

set()

Set a session variable.

public set(string $key, mixed $value) : mixed
Parameters
$key : string

Key to set.

$value : mixed

Value to set.

Return values
mixed —

set_customer_session_cookie()

Sets the session cookie on-demand (usually after adding an item to the cart).

public set_customer_session_cookie(bool $set) : mixed

Since the cookie name (as of 2.1) is prepended with wp, cache systems like batcache will not cache pages when set.

Warning: Cookies will only be set if this is called before the headers are sent.

Parameters
$set : bool

Should the session cookie be set.

Return values
mixed —

update_session_timestamp()

Update the session expiry timestamp.

public update_session_timestamp(string $customer_id, int $timestamp) : mixed
Parameters
$customer_id : string

Customer ID.

$timestamp : int

Timestamp to expire the cookie.

Return values
mixed —

clone_session_data()

Clones a session to the current session. Exclude customer details for privacy reasons.

private clone_session_data(string $clone_from_customer_id) : mixed
Parameters
$clone_from_customer_id : string

The customer ID to clone from.

Return values
mixed —

get_cache_prefix()

Gets a cache prefix. This is used in session names so the entire cache can be invalidated with 1 function call.

private get_cache_prefix() : string
Return values
string —

hash()

Hash a value using wp_fast_hash (from WP 6.8 onwards).

private hash(string $message) : string

This method can be removed when the minimum version supported is 6.8.

Parameters
$message : string

Value to hash.

Return values
string — Hashed value.

init_session_from_request()

Initialize the session from the query string parameter.

private init_session_from_request() : bool

If the current user is logged in, the token session will replace the current user's session. If the current user is logged out, the token session will be cloned to a new session.

Only guest sessions are restored, hence the check for the t_ prefix on the customer ID.

Return values
bool —

is_customer_guest()

Checks if this is an auto-generated customer ID.

private is_customer_guest(string $customer_id) : bool
Parameters
$customer_id : string

Customer ID to check.

Return values
bool — Whether customer ID is randomly generated.

is_session_cookie_valid()

Checks if session cookie is expired, or belongs to a logged out user.

private is_session_cookie_valid() : bool
Return values
bool — Whether session cookie is valid.

is_session_expiring()

Checks if the session is expiring.

private is_session_expiring() : bool
Return values
bool — Whether session is expiring.

migrate_guest_session_to_user_session()

Migrates a guest session to the current user session.

private migrate_guest_session_to_user_session() : mixed
Return values
mixed —

restore_session_data()

Restore the session data from the database.

private restore_session_data() : mixed
Tags
since
10.0.0
Return values
mixed —

session_exists()

Check if a session exists in the database.

private session_exists(string $customer_id) : bool
Parameters
$customer_id : string

Customer ID.

Return values
bool —

verify_hash()

Verify a hash using wp_verify_fast_hash (from WP 6.8 onwards).

private verify_hash(string $message, string $hash) : bool

This method can be removed when the minimum version supported is 6.8.

Parameters
$message : string

Message to verify.

$hash : string

Hash to verify.

Return values
bool — Whether the hash is valid.