CakePHP
  • Documentation
    • Book
    • API
    • Videos
    • Reporting Security Issues
    • Privacy Policy
    • Logos & Trademarks
  • Business Solutions
  • Swag
  • Road Trip
  • Team
  • Community
    • Community
    • Get Involved
    • Issues (Github)
    • Bakery
    • Featured Resources
    • Training
    • Meetups
    • My CakePHP
    • CakeFest
    • Newsletter
    • Linkedin
    • YouTube
    • Facebook
    • Twitter
    • Mastodon
    • Help & Support
    • Forum
    • Stack Overflow
    • IRC
    • Slack
    • Paid Support
CakePHP

C CakePHP 4.3 Strawberry API

  • Project:
    • CakePHP
      • CakePHP
      • Authentication
      • Authorization
      • Chronos
      • Elastic Search
      • Queue
  • Version:
    • 4.3
      • 5.2
      • 5.1
      • 5.0
      • 4.6
      • 4.5
      • 4.4
      • 4.3
      • 4.2
      • 4.1
      • 4.0
      • 3.10
      • 3.9
      • 3.8
      • 3.7
      • 3.6
      • 3.5
      • 3.4
      • 3.3
      • 3.2
      • 3.1
      • 3.0
      • 2.10
      • 2.9
      • 2.8
      • 2.7
      • 2.6
      • 2.5
      • 2.4
      • 2.3
      • 2.2
      • 2.1
      • 2.0
      • 1.3
      • 1.2

Namespaces

  • Global
  • Cake
    • Auth
    • Cache
    • Collection
    • Command
    • Console
    • Controller
    • Core
    • Database
    • Datasource
    • Error
    • Event
    • Filesystem
    • Form
    • Http
      • Client
      • Cookie
      • Exception
      • Middleware
      • Session
    • I18n
    • Log
    • Mailer
    • Network
    • ORM
    • Routing
    • Shell
    • TestSuite
    • Utility
    • Validation
    • View

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

Property Summary

  • $_engine protected
    SessionHandlerInterface

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

  • $_isCLI protected
    bool

    Whether this session is running under a CLI environment

  • $_lifetime protected
    int

    The time in seconds the session will be valid for

  • $_started protected
    bool

    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.

  • 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_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 engine 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 engine key 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|false

Get one of the prebaked default session configurations.

Parameters
string $name

Config name.

Returns
array|false

_hasSession() ¶ protected

_hasSession(): bool

Returns whether a session exists

Returns
bool

_overwrite() ¶ protected

_overwrite(array $old, array $new): void

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

Returns
void

_timedOut() ¶ protected

_timedOut(): bool

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

Returns
bool

check() ¶ public

check(string|null $name = null): bool

Returns true if given variable name is set in session.

Parameters
string|null $name optional

Variable name to check for

Returns
bool

clear() ¶ public

clear(bool $renew = false): void

Clears 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
void

close() ¶ public

close(): true

Write data and close the session

Returns
true

consume() ¶ public

consume(string $name): mixed|null

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|null

create() ¶ public static

create(array $sessionConfig = []): 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:

  • 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
static
See Also
\Cake\Http\Session::__construct()

delete() ¶ public

delete(string $name): void

Removes a variable from session.

Parameters
string $name

Session variable to remove

Returns
void

destroy() ¶ public

destroy(): void

Helper method to destroy invalid sessions.

Returns
void

engine() ¶ public

engine(SessionHandlerInterface|string|null $class = null, array<string, mixed> $options = []): SessionHandlerInterface|null

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
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|null
Throws
InvalidArgumentException

id() ¶ public

id(string|null $id = null): string

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

Id to replace the current session id

Returns
string

options() ¶ public

options(array<string, mixed> $options): void

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<string, mixed> $options

Ini options to set.

Returns
void
Throws
RuntimeException
if any directive could not be set

read() ¶ public

read(string|null $name = null, mixed $default = null): mixed|null

Returns 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|null

readOrFail() ¶ public

readOrFail(string $name): mixed|null

Returns 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|null
Throws
RuntimeException

renew() ¶ public

renew(): void

Restarts this session.

Returns
void

setEngine() ¶ protected

setEngine(SessionHandlerInterface $handler): SessionHandlerInterface

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

Parameters
SessionHandlerInterface $handler

The handler to set

Returns
SessionHandlerInterface

start() ¶ public

start(): bool

Starts the Session.

Returns
bool
Throws
RuntimeException
if the session was already started

started() ¶ public

started(): bool

Determine if Session has already been started.

Returns
bool

write() ¶ public

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

Writes value to given session variable name.

Parameters
array|string $name

Name of variable

mixed $value optional

Value to write

Returns
void

Property Detail

$_engine ¶ protected

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

Type
SessionHandlerInterface

$_isCLI ¶ protected

Whether this session is running under a CLI environment

Type
bool

$_lifetime ¶ protected

The time in seconds the session will be valid for

Type
int

$_started ¶ protected

Indicates whether the sessions has already started

Type
bool
OpenHub
Pingping
Linode
  • Business Solutions
  • Showcase
  • Documentation
  • Book
  • API
  • Videos
  • Reporting Security Issues
  • Privacy Policy
  • Logos & Trademarks
  • Community
  • Get Involved
  • Issues (Github)
  • Bakery
  • Featured Resources
  • Training
  • Meetups
  • My CakePHP
  • CakeFest
  • Newsletter
  • Linkedin
  • YouTube
  • Facebook
  • Twitter
  • Mastodon
  • Help & Support
  • Forum
  • Stack Overflow
  • IRC
  • Slack
  • Paid Support

Generated using CakePHP API Docs