PHP Session library
Translations: Español
PHP library for handling sessions.
- Requirements
- Installation
- Available Classes
- Exceptions Used
- Usage
- Tests
- TODO
- Changelog
- Contribution
- Sponsor
- License
Requirements
-
Operating System: Linux | Windows.
-
PHP versions: 8.0 | 8.1 | 8.2.
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