README

A fork from the great library from josantonius, check him out here: https://github.com/josantonius/php-session

Did a fork to have our namespace across our own libraries and his.

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 pixxel/session

The previous command will only install the necessary files, if you prefer to download the entire source code you can use:

composer require pixxel/session --prefer-source

You can also clone the complete repository with Git:

git clone https://github.com/pixxelfactory/session.git

Available Methods

Available methods in this library:

Starts the session

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

@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

@Return bool

Check if the session is started

$session->isStarted();

@Return bool

Sets an attribute by name

$session->set(string $name, mixed $value = null);

@throws SessionException If session is unstarted

@Return void

Gets an attribute by name

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

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

@Return mixed Value

Gets all attributes

$session->all();

@Return array $_SESSION content

Check if an attribute exists in the session

$session->has(string $name);

@Return bool

Sets several attributes at once

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

$session->replace(array $data);

@throws SessionException If session is unstarted

@Return void

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

@throws SessionException If session is unstarted

@Return mixed Attribute value

Deletes an attribute by name

$session->remove(string $name);

@throws SessionException If session is unstarted

@Return void

Free all session variables

$session->clear();

@throws SessionException If session is unstarted

@Return void

Gets the session ID

$session->getId();

@Return string Session ID

Sets the session ID

$session->setId(string $sessionId);

@throws SessionException If session already started

@Return void

Update the current session id with a newly generated one

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

@throws SessionException If session is unstarted

@Return bool

Gets the session name

$session->getName();

@Return string Session name

Sets the session name

$session->setName(string $name);

@throws SessionException If session already started

@Return void

Destroys the session

$session->destroy();

@throws SessionException If session is unstarted

@Return bool

Quick Start

To use this library with Composer:

use Pixxel\Session;

$session = new Session();

Or instead you can use a facade to access the methods statically:

use Pixxel\Facades\Session;

Usage

Example of use for this library:

- Starts the session

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 session object:

$session->isStarted();

Using the facade:

Session::isStarted();

- Sets an attribute by name

Using session object:

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

Using the facade:

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

- Gets an attribute by name

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 session object:

$session->all();

Using the facade:

Session::all();

- Check if an attribute exists in the session

Using session object:

$session->has('foo');

Using the facade:

Session::has('foo');

- Sets several attributes at once

Using session object:

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

Using the facade:

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

- Deletes an attribute by name and returns its value

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 session object:

$session->remove('foo');

Using the facade:

Session::remove('foo');

- Free all session variables

Using session object:

$session->clear();

Using the facade:

Session::clear();

- Gets the session ID

Using session object:

$session->getId();

Using the facade:

Session::getId();

- Sets the session ID

Using session object:

$session->setId('foo');

Using the facade:

Session::setId('foo');

- Update the current session id with a newly generated one

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 session object:

$session->getName();

Using the facade:

Session::getName();

- Sets the session name

Using session object:

$session->setName('foo');

Using the facade:

Session::setName('foo');

- Destroys the session

Using session object:

$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/pixxelfactory/session.git

cd 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 Josantonius to support my open source work 😊

License

This repository is licensed under the MIT License.

Copyright © 2017-present, Josantonius