PHP Session library
, (*1)
Translations: Español, (*2)
PHP library for handling sessions., (*3)
Requirements
-
Operating System: Linux | Windows., (*4)
-
PHP versions: 8.0 | 8.1 | 8.2 | 8.3., (*5)
Installation
The preferred way to install this extension is through Composer., (*6)
To install PHP Session library, simply:, (*7)
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:, (*8)
composer require josantonius/session --prefer-source
You can also clone the complete repository with Git:, (*9)
git clone https://github.com/josantonius/php-session.git
Available Classes
Session Class
Josantonius\Session\Session, (*10)
Starts the session:, (*11)
/**
* @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:, (*12)
public function isStarted(): bool;
Sets an attribute by name:, (*13)
/**
* @throws SessionNotStartedException if session was not started.
*/
public function set(string $name, mixed $value): void;
Gets an attribute by name:, (*14)
/**
* Optionally defines a default value when the attribute does not exist.
*/
public function get(string $name, mixed $default = null): mixed;
Gets all attributes:, (*15)
public function all(): array;
Check if an attribute exists in the session:, (*16)
public function has(string $name): bool;
Sets several attributes at once:, (*17)
/**
* 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:, (*18)
/**
* 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:, (*19)
/**
* @throws SessionNotStartedException if session was not started.
*/
public function remove(string $name): void;
Free all session variables:, (*20)
/**
* @throws SessionNotStartedException if session was not started.
*/
public function clear(): void;
Gets the session ID:, (*21)
public function getId(): string;
Sets the session ID:, (*22)
/**
* @throws SessionStartedException if session already started.
*/
public function setId(string $sessionId): void;
Update the current session ID with a newly generated one:, (*23)
/**
* @throws SessionNotStartedException if session was not started.
*/
public function regenerateId(bool $deleteOldSession = false): bool;
Gets the session name:, (*24)
public function getName(): string;
Sets the session name:, (*25)
/**
* @throws SessionStartedException if session already started.
*/
public function setName(string $name): void;
Destroys the session:, (*26)
/**
* @throws SessionNotStartedException if session was not started.
*/
public function destroy(): bool;
Session Facade
Josantonius\Session\Facades\Session, (*27)
Starts the session:, (*28)
/**
* @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:, (*29)
public static function isStarted(): bool;
Sets an attribute by name:, (*30)
/**
* @throws SessionNotStartedException if session was not started.
*/
public static function set(string $name, mixed $value): void;
Gets an attribute by name:, (*31)
/**
* Optionally defines a default value when the attribute does not exist.
*/
public static function get(string $name, mixed $default = null): mixed;
Gets all attributes:, (*32)
public static function all(): array;
Check if an attribute exists in the session:, (*33)
public static function has(string $name): bool;
Sets several attributes at once:, (*34)
/**
* 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:, (*35)
/**
* 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:, (*36)
/**
* @throws SessionNotStartedException if session was not started.
*/
public static function remove(string $name): void;
Free all session variables:, (*37)
/**
* @throws SessionNotStartedException if session was not started.
*/
public static function clear(): void;
Gets the session ID:, (*38)
public static function getId(): string;
Sets the session ID:, (*39)
/**
* @throws SessionStartedException if session already started.
*/
public static function setId(string $sessionId): void;
Update the current session ID with a newly generated one:, (*40)
/**
* @throws SessionNotStartedException if session was not started.
*/
public static function regenerateId(bool $deleteOldSession = false): bool;
Gets the session name:, (*41)
public static function getName(): string;
Sets the session name:, (*42)
/**
* @throws SessionStartedException if session already started.
*/
public static function setName(string $name): void;
Destroys the session:, (*43)
/**
* @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:, (*44)
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:, (*45)
git clone https://github.com/josantonius/php-session.git
cd php-session
composer install
Run unit tests with PHPUnit:, (*46)
composer phpunit
Run code standard tests with PHPCS:, (*47)
composer phpcs
Run PHP Mess Detector tests to detect inconsistencies in code style:, (*48)
composer phpmd
Run all previous tests:, (*49)
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., (*50)
Contribution
Please make sure to read the Contributing Guide, before making a pull
request, start a discussion or report a issue., (*51)
Thanks to all contributors! :heart:, (*52)
If this project helps you to reduce your development time,
you can sponsor me to support my open source work :blush:, (*53)
License
This repository is licensed under the MIT License., (*54)
Copyright © 2017-present, Josantonius, (*55)
Wallogit.com
Josantonius