PHPackages                             josantonius/session - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. josantonius/session

ActiveLibrary[Utility & Helpers](/categories/utility)

josantonius/session
===================

PHP library for handling sessions.

v2.0.9(2y ago)7826.9k—4.3%27[1 PRs](https://github.com/josantonius/php-session/pulls)5MITPHPPHP ^8.0CI passing

Since Jan 17Pushed 2mo ago4 watchersCompare

[ Source](https://github.com/josantonius/php-session)[ Packagist](https://packagist.org/packages/josantonius/session)[ GitHub Sponsors](https://github.com/Josantonius)[ RSS](/packages/josantonius-session/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (10)Dependencies (3)Versions (22)Used By (5)

PHP Session library
===================

[](#php-session-library)

[![Latest Stable Version](https://camo.githubusercontent.com/465844f74fd7d3b9947642694fdeda1829c344cb8d949e83369b3c49295eebb7/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f73657373696f6e2f762f737461626c65)](https://packagist.org/packages/josantonius/session)[![License](https://camo.githubusercontent.com/66d4fc2ae9148d0187e744e1aa02fcac3a15bf08f627d5a6bc50b09c1e8d21a5/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f73657373696f6e2f6c6963656e7365)](LICENSE)[![Total Downloads](https://camo.githubusercontent.com/62e0bf9c726c7ba512f491306e197f9c53a2c0201fc800bba878da20aea00e9d/68747470733a2f2f706f7365722e707567782e6f72672f6a6f73616e746f6e6975732f73657373696f6e2f646f776e6c6f616473)](https://packagist.org/packages/josantonius/session)[![CI](https://github.com/josantonius/php-session/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/josantonius/php-session/actions/workflows/ci.yml)[![CodeCov](https://camo.githubusercontent.com/2c0715250f187dc31fb29cc78f2b2d35bef68a1c2c1462f7af5db454b060d383/68747470733a2f2f636f6465636f762e696f2f67682f6a6f73616e746f6e6975732f7068702d73657373696f6e2f6272616e63682f6d61696e2f67726170682f62616467652e737667)](https://codecov.io/gh/josantonius/php-session)[![PSR1](https://camo.githubusercontent.com/b502a899c9aec217e98971160f816f87346be272cf1a25cfa4793f2ee724bfc8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d312d6635373034362e737667)](https://www.php-fig.org/psr/psr-1/)[![PSR4](https://camo.githubusercontent.com/d1c090de87e968254a6658528f3bfe9c9dad422d6047fd1323dc211560182c01/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d342d3962353962362e737667)](https://www.php-fig.org/psr/psr-4/)[![PSR12](https://camo.githubusercontent.com/19c529c6dc0656dcc2a16c1a84af450b7bd0dc7b0571b8f17e4fc9f2414f8821/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5053522d31322d3161626339632e737667)](https://www.php-fig.org/psr/psr-12/)

**Translations**: [Español](.github/lang/es-ES/README.md)

PHP library for handling sessions.

---

- [Requirements](#requirements)
- [Installation](#installation)
- [Available Classes](#available-classes)
    - [Session Class](#session-class)
    - [Session Facade](#session-facade)
- [Exceptions Used](#exceptions-used)
- [Usage](#usage)
- [Tests](#tests)
- [TODO](#todo)
- [Changelog](#changelog)
- [Contribution](#contribution)
- [Sponsor](#sponsor)
- [License](#license)

---

Requirements
------------

[](#requirements)

- Operating System: Linux | Windows.
- PHP versions: 8.0 | 8.1 | 8.2 | 8.3.

Installation
------------

[](#installation)

The preferred way to install this extension is through [Composer](http://getcomposer.org/download/).

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

[](#available-classes)

### Session Class

[](#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

[](#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
---------------

[](#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
-----

[](#usage)

Example of use for this library:

### Starts the session without setting options

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#free-all-session-variables)

```
use Josantonius\Session\Session;

$session = new Session();

$session->clear();
```

```
use Josantonius\Session\Facades\Session;

Session::clear();
```

### Gets the session ID

[](#gets-the-session-id)

```
use Josantonius\Session\Session;

$session = new Session();

$session->getId();
```

```
use Josantonius\Session\Facades\Session;

Session::getId();
```

### Sets the session ID

[](#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

[](#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

[](#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

[](#gets-the-session-name)

```
use Josantonius\Session\Session;

$session = new Session();

$session->getName();
```

```
use Josantonius\Session\Facades\Session;

Session::getName();
```

### Sets the session name

[](#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

[](#destroys-the-session)

```
use Josantonius\Session\Session;

$session = new Session();

$session->destroy();
```

```
use Josantonius\Session\Facades\Session;

Session::destroy();
```

Tests
-----

[](#tests)

To run [tests](tests) you just need [composer](http://getcomposer.org/download/)and to execute the following:

```
git clone https://github.com/josantonius/php-session.git
```

```
cd php-session
```

```
composer install
```

Run unit tests with [PHPUnit](https://phpunit.de/):

```
composer phpunit
```

Run code standard tests with [PHPCS](https://github.com/squizlabs/PHP_CodeSniffer):

```
composer phpcs
```

Run [PHP Mess Detector](https://phpmd.org/) tests to detect inconsistencies in code style:

```
composer phpmd
```

Run all previous tests:

```
composer tests
```

TODO
----

[](#todo)

- Add new feature
- Improve tests
- Improve documentation
- 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
---------

[](#changelog)

Detailed changes for each release are documented in the [release notes](https://github.com/josantonius/php-session/releases).

Contribution
------------

[](#contribution)

Please make sure to read the [Contributing Guide](.github/CONTRIBUTING.md), before making a pull request, start a discussion or report a issue.

Thanks to all [contributors](https://github.com/josantonius/php-session/graphs/contributors)! ❤️

Sponsor
-------

[](#sponsor)

If this project helps you to reduce your development time, [you can sponsor me](https://github.com/josantonius#sponsor) to support my open source work 😊

License
-------

[](#license)

This repository is licensed under the [MIT License](LICENSE).

Copyright © 2017-present, [Josantonius](https://github.com/josantonius#contact)

###  Health Score

54

—

FairBetter than 97% of packages

Maintenance57

Moderate activity, may be stable

Popularity43

Moderate usage in the ecosystem

Community27

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 89.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~141 days

Recently: every ~164 days

Total

20

Last Release

819d ago

Major Versions

1.1.9 → 2.0.02022-06-27

PHP version history (3 changes)1.0.0PHP >=7.0

1.1.1PHP ^5.6 || ^7.0

2.0.0PHP ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4b221283501ec8a9cbaefaf27821a91ae8ddd33bddf1fccc6c6815b7ad216ff1?d=identicon)[Josantonius](/maintainers/Josantonius)

---

Top Contributors

[![josantonius](https://avatars.githubusercontent.com/u/18104336?v=4)](https://github.com/josantonius "josantonius (108 commits)")[![chris86747](https://avatars.githubusercontent.com/u/12914881?v=4)](https://github.com/chris86747 "chris86747 (3 commits)")[![chrisrowley14](https://avatars.githubusercontent.com/u/12914881?v=4)](https://github.com/chrisrowley14 "chrisrowley14 (3 commits)")[![Zork130](https://avatars.githubusercontent.com/u/12914881?v=4)](https://github.com/Zork130 "Zork130 (3 commits)")[![owenvoke](https://avatars.githubusercontent.com/u/1899334?v=4)](https://github.com/owenvoke "owenvoke (2 commits)")[![alirezasalehizadeh](https://avatars.githubusercontent.com/u/66994089?v=4)](https://github.com/alirezasalehizadeh "alirezasalehizadeh (1 commits)")[![peter279k](https://avatars.githubusercontent.com/u/9021747?v=4)](https://github.com/peter279k "peter279k (1 commits)")

---

Tags

cookiephpphp-sessionssessionphpsession

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/josantonius-session/health.svg)

```
[![Health](https://phpackages.com/badges/josantonius-session/health.svg)](https://phpackages.com/packages/josantonius-session)
```

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)