PHP Session library

Translations: Español

PHP library for handling sessions.

Requirements
Installation
Available Classes
- Session Class
- Session Facade
Exceptions Used
Usage
Tests
TODO
Changelog
Contribution
Sponsor
License

Requirements

Operating System: Linux | Windows.
PHP versions: 8.0 | 8.1 | 8.2 | 8.3.

Installation

The preferred way to install this extension is through Composer.

To install PHP Session library, simply:

composer require josantonius/session

The previous command will only install the necessary files, if you prefer to download the entire source code you can use:

composer require josantonius/session --prefer-source

You can also clone the complete repository with Git:

git clone https://github.com/josantonius/php-session.git

Available Classes

Session Class

Josantonius\Session\Session

Starts the session:

/**
 * @throws HeadersSentException        if headers already sent.
 * @throws SessionStartedException     if session already started.
 * @throws WrongSessionOptionException if setting options failed.
 * 
 * @see https://php.net/session.configuration for List of available $options.
 */
public function start(array $options = []): bool;

Check if the session is started:

public function isStarted(): bool;

Sets an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function set(string $name, mixed $value): void;

Gets an attribute by name:

/**
 * Optionally defines a default value when the attribute does not exist.
 */
public function get(string $name, mixed $default = null): mixed;

Gets all attributes:

public function all(): array;

Check if an attribute exists in the session:

public function has(string $name): bool;

Sets several attributes at once:

/**
 * If attributes exist they are replaced, if they do not exist they are created.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public function replace(array $data): void;

Deletes an attribute by name and returns its value:

/**
 * Optionally defines a default value when the attribute does not exist.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public function pull(string $name, mixed $default = null): mixed;

Deletes an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function remove(string $name): void;

Free all session variables:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function clear(): void;

Gets the session ID:

public function getId(): string;

Sets the session ID:

/**
 * @throws SessionStartedException if session already started.
 */
public function setId(string $sessionId): void;

Update the current session ID with a newly generated one:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function regenerateId(bool $deleteOldSession = false): bool;

Gets the session name:

public function getName(): string;

Sets the session name:

/**
 * @throws SessionStartedException if session already started.
 */
public function setName(string $name): void;

Destroys the session:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public function destroy(): bool;

Session Facade

Josantonius\Session\Facades\Session

Starts the session:

/**
 * @throws HeadersSentException        if headers already sent.
 * @throws SessionStartedException     if session already started.
 * @throws WrongSessionOptionException if setting options failed.
 * 
 * @see https://php.net/session.configuration for List of available $options.
 */
public static function start(array $options = []): bool;

Check if the session is started:

public static function isStarted(): bool;

Sets an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function set(string $name, mixed $value): void;

Gets an attribute by name:

/**
 * Optionally defines a default value when the attribute does not exist.
 */
public static function get(string $name, mixed $default = null): mixed;

Gets all attributes:

public static function all(): array;

Check if an attribute exists in the session:

public static function has(string $name): bool;

Sets several attributes at once:

/**
 * If attributes exist they are replaced, if they do not exist they are created.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public static function replace(array $data): void;

Deletes an attribute by name and returns its value:

/**
 * Optionally defines a default value when the attribute does not exist.
 * 
 * @throws SessionNotStartedException if session was not started.
 */
public static function pull(string $name, mixed $default = null): mixed;

Deletes an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function remove(string $name): void;

Free all session variables:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function clear(): void;

Gets the session ID:

public static function getId(): string;

Sets the session ID:

/**
 * @throws SessionStartedException if session already started.
 */
public static function setId(string $sessionId): void;

Update the current session ID with a newly generated one:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function regenerateId(bool $deleteOldSession = false): bool;

Gets the session name:

public static function getName(): string;

Sets the session name:

/**
 * @throws SessionStartedException if session already started.
 */
public static function setName(string $name): void;

Destroys the session:

/**
 * @throws SessionNotStartedException if session was not started.
 */
public static function destroy(): bool;

Exceptions Used

use Josantonius\Session\Exceptions\HeadersSentException;
use Josantonius\Session\Exceptions\SessionException;
use Josantonius\Session\Exceptions\SessionNotStartedException;
use Josantonius\Session\Exceptions\SessionStartedException;
use Josantonius\Session\Exceptions\WrongSessionOptionException;

Usage

Example of use for this library:

Starts the session without setting options

use Josantonius\Session\Session;

$session = new Session();

$session->start();

use Josantonius\Session\Facades\Session;

Session::start();

Starts the session setting options

use Josantonius\Session\Session;

$session = new Session();

$session->start([
    // 'cache_expire' => 180,
    // 'cache_limiter' => 'nocache',
    // 'cookie_domain' => '',
    'cookie_httponly' => true,
    'cookie_lifetime' => 8000,
    // 'cookie_path' => '/',
    'cookie_samesite' => 'Strict',
    'cookie_secure'   => true,
    // 'gc_divisor' => 100,
    // 'gc_maxlifetime' => 1440,
    // 'gc_probability' => true,
    // 'lazy_write' => true,
    // 'name' => 'PHPSESSID',
    // 'read_and_close' => false,
    // 'referer_check' => '',
    // 'save_handler' => 'files',
    // 'save_path' => '',
    // 'serialize_handler' => 'php',
    // 'sid_bits_per_character' => 4,
    // 'sid_length' => 32,
    // 'trans_sid_hosts' => $_SERVER['HTTP_HOST'],
    // 'trans_sid_tags' => 'a=href,area=href,frame=src,form=',
    // 'use_cookies' => true,
    // 'use_only_cookies' => true,
    // 'use_strict_mode' => false,
    // 'use_trans_sid' => false,
]);

use Josantonius\Session\Facades\Session;

Session::start([
    'cookie_httponly' => true,
]);

Check if the session is started

use Josantonius\Session\Session;

$session = new Session();

$session->isStarted();

use Josantonius\Session\Facades\Session;

Session::isStarted();

Sets an attribute by name

use Josantonius\Session\Session;

$session = new Session();

$session->set('foo', 'bar');

use Josantonius\Session\Facades\Session;

Session::set('foo', 'bar');

Gets an attribute by name without setting a default value

use Josantonius\Session\Session;

$session = new Session();

$session->get('foo'); // null if attribute does not exist

use Josantonius\Session\Facades\Session;

Session::get('foo'); // null if attribute does not exist

Gets an attribute by name setting a default value

use Josantonius\Session\Session;

$session = new Session();

$session->get('foo', false); // false if attribute does not exist

use Josantonius\Session\Facades\Session;

Session::get('foo', false); // false if attribute does not exist

Gets all attributes

use Josantonius\Session\Session;

$session = new Session();

$session->all();

use Josantonius\Session\Facades\Session;

Session::all();

Check if an attribute exists in the session

use Josantonius\Session\Session;

$session = new Session();

$session->has('foo');

use Josantonius\Session\Facades\Session;

Session::has('foo');

Sets several attributes at once

use Josantonius\Session\Session;

$session = new Session();

$session->replace(['foo' => 'bar', 'bar' => 'foo']);

use Josantonius\Session\Facades\Session;

Session::replace(['foo' => 'bar', 'bar' => 'foo']);

Deletes an attribute and returns its value or the default value if not exist

use Josantonius\Session\Session;

$session = new Session();

$session->pull('foo'); // null if attribute does not exist

use Josantonius\Session\Facades\Session;

Session::pull('foo'); // null if attribute does not exist

Deletes an attribute and returns its value or the custom value if not exist

use Josantonius\Session\Session;

$session = new Session();

$session->pull('foo', false); // false if attribute does not exist

use Josantonius\Session\Facades\Session;

Session::pull('foo', false); // false if attribute does not exist

Deletes an attribute by name

use Josantonius\Session\Session;

$session = new Session();

$session->remove('foo');

use Josantonius\Session\Facades\Session;

Session::remove('foo');

Free all session variables

use Josantonius\Session\Session;

$session = new Session();

$session->clear();

use Josantonius\Session\Facades\Session;

Session::clear();

Gets the session ID

use Josantonius\Session\Session;

$session = new Session();

$session->getId();

use Josantonius\Session\Facades\Session;

Session::getId();

Sets the session ID

use Josantonius\Session\Session;

$session = new Session();

$session->setId('foo');

use Josantonius\Session\Facades\Session;

Session::setId('foo');

Update the current session ID with a newly generated one

use Josantonius\Session\Session;

$session = new Session();

$session->regenerateId();

use Josantonius\Session\Facades\Session;

Session::regenerateId();

Update the current session ID with a newly generated one deleting the old session

use Josantonius\Session\Session;

$session = new Session();

$session->regenerateId(true);

use Josantonius\Session\Facades\Session;

Session::regenerateId(true);

Gets the session name

use Josantonius\Session\Session;

$session = new Session();

$session->getName();

use Josantonius\Session\Facades\Session;

Session::getName();

Sets the session name

use Josantonius\Session\Session;

$session = new Session();

$session->setName('foo');

use Josantonius\Session\Facades\Session;

Session::setName('foo');

Destroys the session

use Josantonius\Session\Session;

$session = new Session();

$session->destroy();

use Josantonius\Session\Facades\Session;

Session::destroy();

Tests

To run tests you just need composer and to execute the following:

git clone https://github.com/josantonius/php-session.git

cd php-session

composer install

Run unit tests with PHPUnit:

composer phpunit

Run code standard tests with PHPCS:

composer phpcs

Run PHP Mess Detector tests to detect inconsistencies in code style:

composer phpmd

Run all previous tests:

composer tests

TODO

Add new feature
Improve tests
Improve documentation
Improve English translation in the README file
Refactor code for disabled code style rules (see phpmd.xml and phpcs.xml)
Show an example of renewing the session lifetime
Feature to enable/disable exceptions?
Feature to add prefixes in session attributes?

Changelog

Detailed changes for each release are documented in the release notes.

Contribution

Please make sure to read the Contributing Guide, before making a pull request, start a discussion or report a issue.

Thanks to all contributors! ❤️

Sponsor

If this project helps you to reduce your development time, you can sponsor me to support my open source work 😊

License

This repository is licensed under the MIT License.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

PHP Session library

Requirements

Installation

Available Classes

Session Class

Session Facade

Exceptions Used

Usage

Starts the session without setting options

Starts the session setting options

Check if the session is started

Sets an attribute by name

Gets an attribute by name without setting a default value

Gets an attribute by name setting a default value

Gets all attributes

Check if an attribute exists in the session

Sets several attributes at once

Deletes an attribute and returns its value or the default value if not exist

Deletes an attribute and returns its value or the custom value if not exist

Deletes an attribute by name

Free all session variables

Gets the session ID

Sets the session ID

Update the current session ID with a newly generated one

Update the current session ID with a newly generated one deleting the old session

Gets the session name

Sets the session name

Destroys the session

Tests

TODO

Changelog

Contribution

Sponsor

License

Files

README.md

Latest commit

History

README.md

File metadata and controls

PHP Session library

Requirements

Installation

Available Classes

Session Class

Session Facade

Exceptions Used

Usage

Starts the session without setting options

Starts the session setting options

Check if the session is started

Sets an attribute by name

Gets an attribute by name without setting a default value

Gets an attribute by name setting a default value

Gets all attributes

Check if an attribute exists in the session

Sets several attributes at once

Deletes an attribute and returns its value or the default value if not exist

Deletes an attribute and returns its value or the custom value if not exist

Deletes an attribute by name

Free all session variables

Gets the session ID

Sets the session ID

Update the current session ID with a newly generated one

Update the current session ID with a newly generated one deleting the old session

Gets the session name

Sets the session name

Destroys the session

Tests

TODO

Changelog

Contribution

Sponsor

License