PHP Session library

Translations: Español

PHP library for handling sessions.

---

• Requirements
• Installation
• Available Methods
• Quick Start
• Usage
• Tests
• TODO
• Changelog
• Contribution
• Sponsor
• License

---

Requirements

This library is compatible with the PHP versions: 8.0 | 8.1.

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 Methods

Available methods in this library:

Starts the session

$session->start(array $options = []): bool

@see https://php.net/session.configuration for List of available $options and their default values.

@throws HeadersSentException if headers already sent.

@throws SessionStartedException if session already started.

@throws WrongSessionOptionException if setting options failed.

Check if the session is started

$session->isStarted(): bool

Sets an attribute by name

$session->set(string $name, mixed $value): void

@throws SessionNotStartedException if session was not started.

Gets an attribute by name

Optionally defines a default value when the attribute does not exist.

$session->get(string $name, mixed $default = null): mixed

Gets all attributes

$session->all(): array

Check if an attribute exists in the session

$session->has(string $name): bool

Sets several attributes at once

If attributes exist they are replaced, if they do not exist they are created.

$session->replace(array $data): void

@throws SessionNotStartedException if session was not started.

Deletes an attribute by name and returns its value

Optionally defines a default value when the attribute does not exist.

$session->pull(string $name, mixed $default = null): mixed

@throws SessionNotStartedException if session was not started.

Deletes an attribute by name

$session->remove(string $name): void

@throws SessionNotStartedException if session was not started.

Free all session variables

$session->clear(): void

@throws SessionNotStartedException if session was not started.

Gets the session ID

$session->getId(): string

Sets the session ID

$session->setId(string $sessionId): void

@throws SessionStartedException if session already started.

Update the current session id with a newly generated one

$session->regenerateId(bool $deleteOldSession = false): bool

@throws SessionNotStartedException if session was not started.

Gets the session name

$session->getName(): string

Sets the session name

$session->setName(string $name): void

@throws SessionStartedException if session already started.

Destroys the session

$session->destroy(): bool

@throws SessionNotStartedException if session was not started.

Quick Start

To use this library with Composer:

Using objects

use Josantonius\Session\Session;

$session = new Session();

Using the facade

Alternatively you can use a facade to access the methods statically:

use Josantonius\Session\Facades\Session;

Usage

Example of use for this library:

- Starts the session

Using objects:

Without setting options:

$session->start();

Setting options:

$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,
]);

Using the facade:

Session::start();

- Check if the session is started

Using objects:

$session->isStarted();

Using the facade:

Session::isStarted();

- Sets an attribute by name

Using objects:

$session->set('foo', 'bar');

Using the facade:

Session::set('foo', 'bar');

- Gets an attribute by name

Using objects:

Without default value if attribute does not exist:

$session->get('foo'); // null if attribute does not exist

With default value if attribute does not exist:

$session->get('foo', false); // false if attribute does not exist

Using the facade:

Session::get('foo');

- Gets all attributes

Using objects:

$session->all();

Using the facade:

Session::all();

- Check if an attribute exists in the session

Using objects:

$session->has('foo');

Using the facade:

Session::has('foo');

- Sets several attributes at once

Using objects:

$session->replace(['foo' => 'bar', 'bar' => 'foo']);

Using the facade:

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

- Deletes an attribute by name and returns its value

Using objects:

Without default value if attribute does not exist:

$session->pull('foo'); // null if attribute does not exist

With default value if attribute does not exist:

$session->pull('foo', false); // false if attribute does not exist

Using the facade:

Session::pull('foo');

- Deletes an attribute by name

Using objects:

$session->remove('foo');

Using the facade:

Session::remove('foo');

- Free all session variables

Using objects:

$session->clear();

Using the facade:

Session::clear();

- Gets the session ID

Using objects:

$session->getId();

Using the facade:

Session::getId();

- Sets the session ID

Using objects:

$session->setId('foo');

Using the facade:

Session::setId('foo');

- Update the current session id with a newly generated one

Using objects:

Regenerate ID without deleting the old session:

$session->regenerateId();

Regenerate ID by deleting the old session:

$session->regenerateId(true);

Using the facade:

Session::regenerateId();

- Gets the session name

Using objects:

$session->getName();

Using the facade:

Session::getName();

- Sets the session name

Using objects:

$session->setName('foo');

Using the facade:

Session::setName('foo');

- Destroys the session

Using objects:

$session->destroy();

Using the facade:

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