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. josantonius/session

ActiveLibrary

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

PHP library for handling sessions.

v2.0.9(1y ago)7825.5k↓22.2%27[1 PRs](https://github.com/josantonius/php-session/pulls)5MITPHPPHP ^8.0

Since Jan 17Pushed 1y 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 1mo 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
- 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
---------

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

48

—

FairBetter than 95% of packages

Maintenance31

Infrequent updates — may be unmaintained

Popularity43

Moderate usage in the ecosystem

Community26

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 93.9% 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

729d 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 (107 commits)")[![chrisrowley14](https://avatars.githubusercontent.com/u/12914881?v=4)](https://github.com/chrisrowley14 "chrisrowley14 (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)