PHP Session library

Translations: Español

PHP library for handling sessions.

Version 1.x is considered as deprecated and unsupported. In this version (2.x) the library was completely restructured. It is recommended to review the documentation for this version and make the necessary changes before starting to use it, as it not be compatible with version 1.x.

---

• 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 SessionException if headers already sent.

@throws SessionException if session already started.

@throws SessionException 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 SessionException if session is unstarted.

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);

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 SessionException if session is unstarted.

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 SessionException if session is unstarted.

Deletes an attribute by name

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

@throws SessionException if session is unstarted.

Free all session variables

$session->clear(): void

@throws SessionException if session is unstarted.

Gets the session ID

$session->getId() string

Sets the session ID

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

@throws SessionException if session already started.

Update the current session id with a newly generated one

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

@throws SessionException if session is unstarted.

Gets the session name

$session->getName(): string

Sets the session name

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

@throws SessionException if session already started.

Destroys the session

$session->destroy(): bool

@throws SessionException if session is unstarted.

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