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

This library is compatible with the PHP versions: 8.0 | 8.1.

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

use Josantonius\Session\Session;

Create object:

$session = new 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.
 */
$session->start(array $options = []): bool

Check if the session is started:

$session->isStarted(): bool

Sets an attribute by name:

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

Gets an attribute by name:

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

Gets all attributes:

$session->all(): array

Check if an attribute exists in the session:

$session->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.
 */
$session->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.
 */
$session->pull(string $name, mixed $default = null): mixed

Deletes an attribute by name:

/**
 * @throws SessionNotStartedException if session was not started.
 */
$session->remove(string $name): void

Free all session variables:

/**
 * @throws SessionNotStartedException if session was not started.
 */
$session->clear(): void

Gets the session ID:

$session->getId(): string

Sets the session ID:

/**
 * @throws SessionStartedException if session already started.
 */
$session->setId(string $sessionId): void

Update the current session ID with a newly generated one:

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

Gets the session name:

$session->getName(): string

Sets the session name:

/**
 * @throws SessionStartedException if session already started.
 */
$session->setName(string $name): void

Destroys the session:

/**
 * @throws SessionNotStartedException if session was not started.
 */
$session->destroy(): bool

Session Facade

use 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.
 */
Session::start(array $options = []): bool

Check if the session is started:

Session::isStarted(): bool

Sets an attribute by name:

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

Gets an attribute by name:

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

Gets all attributes:

Session::all(): array

Check if an attribute exists in the session:

Session::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.
 */
Session::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.
 */
Session::pull(string $name, mixed $default = null): mixed

Deletes an attribute by name:

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

Free all session variables:

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

Gets the session ID:

Session::getId(): string

Sets the session ID:

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

Update the current session ID with a newly generated one:

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

Gets the session name:

Session::getName(): string

Sets the session name:

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

Destroys the session:

/**
 * @throws SessionNotStartedException if session was not started.
 */
Session::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! :heart:

Sponsor

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

License

This repository is licensed under the MIT License.

Copyright © 2017-present, Josantonius