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

Check if the session is started:

publicfunction isStarted(): bool;

Sets an attribute by name:

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

Gets an attribute by name:

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

Gets all attributes:

publicfunction all(): array;

Check if an attribute exists in the session:

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

Deletes an attribute by name:

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

Free all session variables:

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

Gets the session ID:

publicfunction getId(): string;

Sets the session ID:

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

Update the current session ID with a newly generated one:

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

Gets the session name:

publicfunction getName(): string;

Sets the session name:

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

Destroys the session:

/** * @throws SessionNotStartedException if session was not started. */publicfunction 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. */publicstaticfunction start(array$options = []): bool;

Check if the session is started:

publicstaticfunction isStarted(): bool;

Sets an attribute by name:

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

Gets an attribute by name:

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

Gets all attributes:

publicstaticfunction all(): array;

Check if an attribute exists in the session:

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

Deletes an attribute by name:

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

Free all session variables:

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

Gets the session ID:

publicstaticfunction getId(): string;

Sets the session ID:

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

Update the current session ID with a newly generated one:

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

Gets the session name:

publicstaticfunction getName(): string;

Sets the session name:

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

Destroys the session:

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

Exceptions Used

useJosantonius\Session\Exceptions\HeadersSentException;
useJosantonius\Session\Exceptions\SessionException;
useJosantonius\Session\Exceptions\SessionNotStartedException;
useJosantonius\Session\Exceptions\SessionStartedException;
useJosantonius\Session\Exceptions\WrongSessionOptionException;

Usage

Example of use for this library:

Starts the session without setting options

useJosantonius\Session\Session;
$session = newSession();
$session->start();

useJosantonius\Session\Facades\Session;
Session::start();

Starts the session setting options

useJosantonius\Session\Session;
$session = newSession();
$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,
]);

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

Check if the session is started

useJosantonius\Session\Session;
$session = newSession();
$session->isStarted();

useJosantonius\Session\Facades\Session;
Session::isStarted();

Sets an attribute by name

useJosantonius\Session\Session;
$session = newSession();
$session->set('foo', 'bar');

useJosantonius\Session\Facades\Session;
Session::set('foo', 'bar');

Gets an attribute by name without setting a default value

useJosantonius\Session\Session;
$session = newSession();
$session->get('foo'); // null if attribute does not exist

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

Gets an attribute by name setting a default value

useJosantonius\Session\Session;
$session = newSession();
$session->get('foo', false); // false if attribute does not exist

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

Gets all attributes

useJosantonius\Session\Session;
$session = newSession();
$session->all();

useJosantonius\Session\Facades\Session;
Session::all();

Check if an attribute exists in the session

useJosantonius\Session\Session;
$session = newSession();
$session->has('foo');

useJosantonius\Session\Facades\Session;
Session::has('foo');

Sets several attributes at once

useJosantonius\Session\Session;
$session = newSession();
$session->replace(['foo' => 'bar', 'bar' => 'foo']);

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

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

useJosantonius\Session\Session;
$session = newSession();
$session->pull('foo'); // null if attribute does not exist

useJosantonius\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

useJosantonius\Session\Session;
$session = newSession();
$session->pull('foo', false); // false if attribute does not exist

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

Deletes an attribute by name

useJosantonius\Session\Session;
$session = newSession();
$session->remove('foo');

useJosantonius\Session\Facades\Session;
Session::remove('foo');

Free all session variables

useJosantonius\Session\Session;
$session = newSession();
$session->clear();

useJosantonius\Session\Facades\Session;
Session::clear();

Gets the session ID

useJosantonius\Session\Session;
$session = newSession();
$session->getId();

useJosantonius\Session\Facades\Session;
Session::getId();

Sets the session ID

useJosantonius\Session\Session;
$session = newSession();
$session->setId('foo');

useJosantonius\Session\Facades\Session;
Session::setId('foo');

Update the current session ID with a newly generated one

useJosantonius\Session\Session;
$session = newSession();
$session->regenerateId();

useJosantonius\Session\Facades\Session;
Session::regenerateId();

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

useJosantonius\Session\Session;
$session = newSession();
$session->regenerateId(true);

useJosantonius\Session\Facades\Session;
Session::regenerateId(true);

Gets the session name

useJosantonius\Session\Session;
$session = newSession();
$session->getName();

useJosantonius\Session\Facades\Session;
Session::getName();

Sets the session name

useJosantonius\Session\Session;
$session = newSession();
$session->setName('foo');

useJosantonius\Session\Facades\Session;
Session::setName('foo');

Destroys the session

useJosantonius\Session\Session;
$session = newSession();
$session->destroy();

useJosantonius\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
• 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