README

Horizom Session

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

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

composer require horizom/session --prefer-source

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 Horizom\Session\Session;

$session = new Session();

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

use Horizom\Session\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();

License

This repository is licensed under the MIT License.