README

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.

Copyright © 2017-present, Josantonius