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.
Property Summary
-
$_engine protected
SessionHandlerInterfaceThe Session handler instance used as an engine for persisting the session data.
-
$_isCLI protected
boolWhether this session is running under a CLI environment
-
$_lifetime protected
intThe time in seconds the session will be valid for
-
$_started protected
boolIndicates whether the sessions has already started
-
$headerSentInfo protected
array{filename: string, line: int}|nullInfo about where the headers were sent.
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
$optionsand set them to the respective value in the passed array. -
read() public
Returns given session variable, or all of them, if no parameters given.
-
readOrFail() public
Returns given session variable, or throws Exception if not found.
-
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<string, mixed> $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_pathphp.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
enginekey. 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 theenginekey to an already instantiated session handler object.
Parameters
-
array<string, mixed>$config optional The Configuration to apply to this session object
_defaultConfig() ¶ protected static
_defaultConfig(string $name): array|falseGet one of the prebaked default session configurations.
Parameters
-
string$name Config name.
Returns
array|false_overwrite() ¶ protected
_overwrite(array $old, array $new): voidUsed 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
Returns
void_timedOut() ¶ protected
_timedOut(): boolReturns true if the session is no longer valid because the last time it was accessed was after the configured timeout.
Returns
boolcheck() ¶ public
check(string|null $name = null): boolReturns true if given variable name is set in session.
Parameters
-
string|null$name optional Variable name to check for
Returns
boolclear() ¶ public
clear(bool $renew = false): voidClears the session.
Optionally it also clears the session id and renews the session.
Parameters
-
bool$renew optional If session should be renewed, as well. Defaults to false.
Returns
voidconsume() ¶ public
consume(string $name): mixed|nullReads 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|nullcreate() ¶ public static
create(array $sessionConfig = []): staticReturns 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
configkey 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
sessionsor amodelkey 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
staticSee Also
delete() ¶ public
delete(string $name): voidRemoves a variable from session.
Parameters
-
string$name Session variable to remove
Returns
voidengine() ¶ public
engine(SessionHandlerInterface|string|null $class = null, array<string, mixed> $options = []): SessionHandlerInterface|nullSets 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
-
SessionHandlerInterface|string|null$class optional The session handler to use
-
array<string, mixed>$options optional the options to pass to the SessionHandler constructor
Returns
SessionHandlerInterface|nullThrows
InvalidArgumentExceptionid() ¶ public
id(string|null $id = null): stringReturns 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 Id to replace the current session id
Returns
stringoptions() ¶ public
options(array<string, mixed> $options): voidCalls 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<string, mixed>$options Ini options to set.
Returns
voidThrows
RuntimeExceptionif any directive could not be set
read() ¶ public
read(string|null $name = null, mixed $default = null): mixed|nullReturns given session variable, or all of them, if no parameters given.
Parameters
-
string|null$name optional The name of the session variable (or a path as sent to Hash.extract)
-
mixed$default optional The return value when the path does not exist
Returns
mixed|nullreadOrFail() ¶ public
readOrFail(string $name): mixed|nullReturns given session variable, or throws Exception if not found.
Parameters
-
string$name The name of the session variable (or a path as sent to Hash.extract)
Returns
mixed|nullThrows
RuntimeExceptionsetEngine() ¶ protected
setEngine(SessionHandlerInterface $handler): SessionHandlerInterfaceSet the engine property and update the session handler in PHP.
Parameters
-
SessionHandlerInterface$handler The handler to set
Returns
SessionHandlerInterfacestart() ¶ public
start(): boolStarts the Session.
Returns
boolThrows
RuntimeExceptionif the session was already started
write() ¶ public
write(array|string $name, mixed $value = null): voidWrites value to given session variable name.
Parameters
-
array|string$name Name of variable
-
mixed$value optional Value to write
Returns
void