Class Session

This class is a wrapper for the native PHP session functions. It provides several defaults for the most common session configuration via external handlers and helps with using session in cli without any warnings.

Sessions can be created from the defaults using Session::create() or you can get an instance of a new session by just instantiating this class and passing the complete options you want to use.

When specific options are omitted, this class will take its defaults from the configuration values from the session.* directives in php.ini. This class will also alter such directives when configuration values are provided.

Namespace: Cake\Http
Location: Http/Session.php

Properties summary

$_engine protected

SessionHandlerInterface

The Session handler instance used as an engine for persisting the session data.
$_isCLI protected

boolean

Whether this session is running under a CLI environment
$_lifetime protected

integer

The time in seconds the session will be valid for
$_started protected

boolean

Indicates whether the sessions has already started

Method Summary

__construct() public

Constructor.
_defaultConfig() protected static

Get one of the prebaked default session configurations.
_hasSession() protected

Returns whether a session exists
_overwrite() protected

Used to write new data to _SESSION, since PHP doesn't like us setting the _SESSION var itself.
_timedOut() protected

Returns true if the session is no longer valid because the last time it was accessed was after the configured timeout.
check() public

Returns true if given variable name is set in session.
clear() public

Clears the session.
close() public

Write data and close the session
consume() public

Reads and deletes a variable from session.
create() public static

Returns a new instance of a session after building a configuration bundle for it. This function allows an options array which will be used for configuring the session and the handler to be used. The most important key in the configuration array is defaults, which indicates the set of configurations to inherit from, the possible defaults are:
delete() public

Removes a variable from session.
destroy() public

Helper method to destroy invalid sessions.
engine() public

Sets the session handler instance to use for this session. If a string is passed for the first argument, it will be treated as the class name and the second argument will be passed as the first argument in the constructor.
id() public

Returns the session id. Calling this method will not auto start the session. You might have to manually assert a started session.
options() public

Calls ini_set for each of the keys in $options and set them to the respective value in the passed array.
read() public

Returns given session variable, or all of them, if no parameters given.
renew() public

Restarts this session.
setEngine() protected

Set the engine property and update the session handler in PHP.
start() public

Starts the Session.
started() public

Determine if Session has already been started.
write() public

Writes value to given session variable name.

Method Detail

__construct() public ¶

__construct( array $config = [] )

Constructor.

Configuration:

timeout: The time in minutes the session should be valid for.
cookiePath: The url path for which session cookie is set. Maps to the session.cookie_path php.ini config. Defaults to base path of app.
ini: A list of php.ini directives to change before the session start.
handler: An array containing at least the class key. To be used as the session engine for persisting data. The rest of the keys in the array will be passed as the configuration array for the engine. You can set the class key to an already instantiated session handler object.

Parameters

array $config optional []: The Configuration to apply to this session object

_defaultConfig() protected static ¶

_defaultConfig( string $name )

Get one of the prebaked default session configurations.

Parameters

string $name: Config name.

Returns

boolean|array

_hasSession() protected ¶

_hasSession( )

Returns whether a session exists

Returns

boolean

_overwrite() protected ¶

_overwrite( array $old , array $new )

Used to write new data to _SESSION, since PHP doesn't like us setting the _SESSION var itself.

Parameters

array $old: Set of old variables => values
array $new: New set of variable => value

_timedOut() protected ¶

_timedOut( )

Returns true if the session is no longer valid because the last time it was accessed was after the configured timeout.

Returns

boolean

check() public ¶

check( string|null $name = null )

Returns true if given variable name is set in session.

Parameters

string|null $name optional null: Variable name to check for

Returns

boolean
True if variable is there

clear() public ¶

clear( boolean $renew = false )

Clears the session.

Optionally it also clears the session id and renews the session.

Parameters

boolean $renew optional false: If session should be renewed, as well. Defaults to false.

close() public ¶

close( )

Write data and close the session

Returns

boolean
True if session was started

consume() public ¶

consume( string $name )

Reads and deletes a variable from session.

Parameters

string $name: The key to read and remove (or a path as sent to Hash.extract).

Returns

mixed

The value of the session variable, null if session not available, session not started, or provided name not found in the session.

create() public static ¶

create( array $sessionConfig = [] )

Returns a new instance of a session after building a configuration bundle for it. This function allows an options array which will be used for configuring the session and the handler to be used. The most important key in the configuration array is defaults, which indicates the set of configurations to inherit from, the possible defaults are:

php: just use session as configured in php.ini
cache: Use the CakePHP caching system as an storage for the session, you will need to pass the config key with the name of an already configured Cache engine.
database: Use the CakePHP ORM to persist and manage sessions. By default this requires a table in your database named sessions or a model key in the configuration to indicate which Table object to use.
cake: Use files for storing the sessions, but let CakePHP manage them and decide where to store them.

The full list of options follows:

defaults: either 'php', 'database', 'cache' or 'cake' as explained above.
handler: An array containing the handler configuration
ini: A list of php.ini directives to set before the session starts.
timeout: The time in minutes the session should stay active

Parameters

array $sessionConfig optional []: Session config.

Returns

Cake\Http\Session

See

\Cake\Http\Session::__construct()

delete() public ¶

delete( string $name )

Removes a variable from session.

Parameters

string $name: Session variable to remove

destroy() public ¶

destroy( )

Helper method to destroy invalid sessions.

engine() public ¶

engine( string|SessionHandlerInterface|null $class = null , array $options = [] )

Sets the session handler instance to use for this session. If a string is passed for the first argument, it will be treated as the class name and the second argument will be passed as the first argument in the constructor.

If an instance of a SessionHandlerInterface is provided as the first argument, the handler will be set to it.

If no arguments are passed it will return the currently configured handler instance or null if none exists.

Parameters

string|SessionHandlerInterface|null $class optional null: The session handler to use
array $options optional []: the options to pass to the SessionHandler constructor

Returns

SessionHandlerInterface|null

Throws

InvalidArgumentException

id() public ¶

id( string|null $id = null )

Returns the session id. Calling this method will not auto start the session. You might have to manually assert a started session.

Passing an id into it, you can also replace the session id if the session has not already been started. Note that depending on the session handler, not all characters are allowed within the session id. For example, the file session handler only allows characters in the range a-z A-Z 0-9 , (comma) and - (minus).

Parameters

string|null $id optional null: Id to replace the current session id

Returns

string
Session id

options() public ¶

options( array $options )

Calls ini_set for each of the keys in $options and set them to the respective value in the passed array.

Example:

$session->options(['session.use_cookies' => 1]);

Parameters

array $options: Ini options to set.

Throws

RuntimeException
if any directive could not be set

read() public ¶

read( string|null $name = null )

Returns given session variable, or all of them, if no parameters given.

Parameters

string|null $name optional null: The name of the session variable (or a path as sent to Hash.extract)

Returns

string|array|null

The value of the session variable, null if session not available, session not started, or provided name not found in the session.

renew() public ¶

renew( )

Restarts this session.

setEngine() protected ¶

setEngine( SessionHandlerInterface $handler )

Set the engine property and update the session handler in PHP.

Parameters

SessionHandlerInterface $handler: The handler to set

Returns

SessionHandlerInterface

start() public ¶

start( )

Starts the Session.

Returns

boolean
True if session was started

Throws

RuntimeException
if the session was already started

started() public ¶

started( )

Determine if Session has already been started.

Returns

boolean
True if session has been started.

write() public ¶

write( string|array $name , mixed $value = null )

Writes value to given session variable name.

Parameters

string|array $name: Name of variable
mixed $value optional null: Value to write

Properties detail

`$_engine` ¶

protected SessionHandlerInterface

The Session handler instance used as an engine for persisting the session data.

`$_isCLI` ¶

protected boolean

Whether this session is running under a CLI environment

false

`$_lifetime` ¶

protected integer

The time in seconds the session will be valid for

`$_started` ¶

protected boolean

Indicates whether the sessions has already started

Namespaces

Classes

Class Session

Properties summary

Method Summary

__construct() public

_defaultConfig() protected static

_hasSession() protected

_overwrite() protected

_timedOut() protected

check() public

clear() public

close() public

consume() public

create() public static

delete() public

destroy() public

engine() public

id() public

options() public

read() public

renew() public

setEngine() protected

start() public

started() public

write() public

Method Detail

__construct() public ¶

Configuration:

Parameters

_defaultConfig() protected static ¶

Parameters

Returns

_hasSession() protected ¶

Returns

_overwrite() protected ¶

Parameters

_timedOut() protected ¶

Returns

check() public ¶

Parameters

Returns

clear() public ¶

Parameters

close() public ¶

Returns

consume() public ¶

Parameters

Returns

create() public static ¶

Parameters

Returns

See

delete() public ¶

Parameters

destroy() public ¶

engine() public ¶

Parameters

Returns

Throws

id() public ¶

Parameters

Returns

options() public ¶

Example:

Parameters

Throws

read() public ¶

Parameters

Returns

renew() public ¶

setEngine() protected ¶

Parameters

Returns

start() public ¶

Returns

Throws

started() public ¶

Returns

write() public ¶

`$_engine` ¶

`$_isCLI` ¶

`$_lifetime` ¶

`$_started` ¶