PHPackages                             pinga/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. [HTTP & Networking](/categories/http)
4. /
5. pinga/session

ActiveLibrary[HTTP & Networking](/categories/http)

pinga/session
=============

Modern session management for PHP

v0.1.4(3y ago)069711MITPHPPHP >=8.1.0

Since Mar 9Pushed 1w ago1 watchersCompare

[ Source](https://github.com/getpinga/session)[ Packagist](https://packagist.org/packages/pinga/session)[ Docs](https://github.com/getpinga/session)[ RSS](/packages/pinga-session/feed)WikiDiscussions main Synced 2w ago

READMEChangelog (6)Dependencies (1)Versions (6)Used By (1)

Pinga Session
=============

[](#pinga-session)

Modern session management for PHP with safer cookie defaults and support for PHP's native session storage handlers.

Pinga Session works with traditional file-based sessions, Redis through the `phpredis` extension, and other handlers supported by PHP. Application code does not change when switching storage backends.

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

[](#requirements)

- PHP 8.3 or newer
- The PHP Redis extension when using Redis

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

[](#installation)

Install the package using Composer:

```
composer require pinga/session
```

Usage
-----

[](#usage)

```
use Pinga\Session\Session;

if (!Session::start()) {
    throw new RuntimeException('Unable to start the session');
}

Session::set('user_id', 123);
Session::set('username', 'example');

$userId = Session::get('user_id');
$username = Session::get('username', 'guest');

Session::close();
```

Call `Session::close()` after the last session change to write the data and release the session lock early.

Changes made to `$_SESSION` after `Session::close()` will not be persisted unless the session is started again.

Available methods
-----------------

[](#available-methods)

```
Session::start();
Session::id();
Session::regenerate();
Session::has('key');
Session::get('key', $defaultValue);
Session::take('key', $defaultValue);
Session::set('key', $value);
Session::delete('key');
Session::close();
Session::isActive();
```

`Session::take()` returns a value and removes it from the session, making it useful for flash messages.

Regenerate the session ID after authentication or a privilege change:

```
if (!Session::regenerate()) {
    throw new RuntimeException('Unable to regenerate the session ID');
}

Session::set('user_id', $userId);
```

SameSite cookies
----------------

[](#samesite-cookies)

The default SameSite policy is `Lax`.

```
Session::start(Session::SAME_SITE_RESTRICTION_LAX);
```

Available policies are:

```
Session::SAME_SITE_RESTRICTION_NONE;
Session::SAME_SITE_RESTRICTION_LAX;
Session::SAME_SITE_RESTRICTION_STRICT;
```

`SameSite=None` requires a secure HTTPS cookie:

```
Session::start(
    Session::SAME_SITE_RESTRICTION_NONE,
    ['cookie_secure' => true]
);
```

SameSite cookies are an additional protection and do not replace CSRF tokens for state-changing requests.

Storage backends
----------------

[](#storage-backends)

Pinga Session does not choose the storage backend itself. PHP selects the backend through `session.save_handler` and `session.save_path`.

The same application code works with both file and Redis storage.

### File sessions

[](#file-sessions)

File-based sessions require no additional PHP extension:

```
session.save_handler = files
session.save_path = "/var/lib/php/sessions"
```

The session directory must exist, be writable by PHP, and not be publicly accessible.

### Redis sessions

[](#redis-sessions)

Install and enable the PHP Redis extension. On Debian or Ubuntu:

```
sudo apt install php-redis
```

Verify that it is enabled:

```
php -m | grep redis
```

When Redis runs on the same server, a Unix socket is recommended:

```
session.save_handler = redis
session.save_path = "unix:///run/redis/redis-server.sock?prefix=pinga_session:&timeout=1&read_timeout=1"
```

Adjust the socket path to match your Redis installation.

Alternatively, use a TCP connection:

```
session.save_handler = redis
session.save_path = "tcp://127.0.0.1:6379?prefix=pinga_session:&timeout=1&read_timeout=1"
```

Recommended production settings
-------------------------------

[](#recommended-production-settings)

These settings apply to both file and Redis sessions:

```
session.auto_start = 0

session.use_strict_mode = 1
session.use_cookies = 1
session.use_only_cookies = 1
session.use_trans_sid = 0

session.gc_maxlifetime = 1800

session.cookie_lifetime = 0
session.cookie_path = /
session.cookie_secure = 1
session.cookie_httponly = 1
session.cookie_samesite = Lax
```

`session.cookie_secure` requires HTTPS. Set it to `0` only in a local HTTP development environment.

When using Redis, also enable session locking:

```
redis.session.locking_enabled = 1

; Must be longer than the application's normal maximum request time.
redis.session.lock_expire = 60

; Allow approximately two seconds to acquire a session lock.
redis.session.lock_wait_time = 20000
redis.session.lock_retries = 100
```

For production, keep Redis on a private network or Unix socket. Use authentication, ACLs and TLS when connecting to a remote Redis server.

If Redis is unavailable, `Session::start()` can fail. Applications should handle this safely instead of silently falling back to file sessions.

Switching between files and Redis
---------------------------------

[](#switching-between-files-and-redis)

To use file storage:

```
session.save_handler = files
session.save_path = "/var/lib/php/sessions"
```

To use Redis through a Unix socket:

```
session.save_handler = redis
session.save_path = "unix:///run/redis/redis-server.sock?prefix=pinga_session:&timeout=1&read_timeout=1"
```

Or through TCP:

```
session.save_handler = redis
session.save_path = "tcp://127.0.0.1:6379?prefix=pinga_session:&timeout=1&read_timeout=1"
```

After changing the configuration, restart PHP-FPM or the relevant web server.

Existing sessions are not migrated when switching storage backends. Users with sessions stored in the previous backend may need to sign in again.

No application code changes are required.

License
-------

[](#license)

Pinga Session is licensed under the MIT License.

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance64

Regular maintenance activity

Popularity18

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~0 days

Total

5

Last Release

1257d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/f8f87416e80fdfb906a1e9d206c9a20584ae27bdd20815170b69efd49e8e9436?d=identicon)[getpinga](/maintainers/getpinga)

---

Top Contributors

[![getpinga](https://avatars.githubusercontent.com/u/121483313?v=4)](https://github.com/getpinga "getpinga (9 commits)")

---

Tags

httpxsscsrfsamesitesame-site

### Embed Badge

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

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

###  Alternatives

[delight-im/cookie

Modern cookie management for PHP

1681.3M15](/packages/delight-im-cookie)[guzzlehttp/psr7

PSR-7 message implementation that also provides common utility methods

7.9k1.1B4.4k](/packages/guzzlehttp-psr7)[psr/http-message

Common interface for HTTP messages

7.0k1.1B8.0k](/packages/psr-http-message)[psr/http-factory

PSR-17: Common interfaces for PSR-7 HTTP message factories

1.9k766.7M3.3k](/packages/psr-http-factory)[psr/http-client

Common interface for HTTP clients

1.7k750.0M3.6k](/packages/psr-http-client)[paragonie/cookie

Modern cookie management for PHP 7

5658.2k2](/packages/paragonie-cookie)

PHPackages © 2026

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