josantonius / session
PHP library for handling sessions.
Fund package maintenance!
Josantonius
Installs: 20 886
Dependents: 5
Suggesters: 0
Security: 0
Stars: 73
Watchers: 5
Forks: 28
Open Issues: 0
Requires
- php: ^8.0
Requires (Dev)
- phpmd/phpmd: ^2.12
- phpunit/phpunit: ^9.5
- squizlabs/php_codesniffer: ^3.7
README
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 | 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