PHPackages                             joby/smol-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. joby/smol-session

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

joby/smol-session
=================

An opinionated PHP session management library, designed to expose a simple API but provide smart performance optimizations and minimize session creation and locking.

v1.1.2(4mo ago)032↓92.9%1MITPHPPHP >=8.3CI passing

Since Dec 17Pushed 4mo agoCompare

[ Source](https://github.com/joby-lol/smol-session)[ Packagist](https://packagist.org/packages/joby/smol-session)[ RSS](/packages/joby-smol-session/feed)WikiDiscussions main Synced 3d ago

READMEChangelog (4)Dependencies (3)Versions (5)Used By (1)

smolSession
===========

[](#smolsession)

An opinionated PHP session management library designed to expose a simple API while providing smart performance optimizations and minimizing session creation and locking.

Features
--------

[](#features)

- **Lazy session creation** - Sessions are only started when data is actually written, avoiding unnecessary cookie traffic
- **Minimized locking** - Sessions are only locked once on first read, and again if necessary during commits, not for the entire response lifecycle
- **Atomic updates** - Operations like increments that apply atomically on commit are possible
- **Simple static API** - Clean, straightforward interface for common session operations

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

[](#installation)

```
composer require joby/smol-session
```

Usage
-----

[](#usage)

```
use Joby\Smol\Session\Session;

// Set values (queued, doesn't lock the session)
Session::set('user_id', 123);
Session::set('username', 'john_doe');

// Increment a counter (queued, doesn't lock the session, will apply to actual value upon commit to avoid race conditions)
Session::increment('page_views');
Session::increment('score', 10);

// Unset values (queued, doesn't lock the session)
Session::unset('temp_data');

// Read values (applies queued updates to cached values for convenience)
$userId = Session::get('user_id');
$views = Session::get('page_views');

// Commit all changes at once atomically, does not reopen session if no changes are queued
Session::commit();

// Can rotate session IDs
Session::rotate();

// Can also destroy the session, deleting all data and unsetting the cookie
Session::destroy();
```

Typed Getters
-------------

[](#typed-getters)

smolSession provides type-safe getter methods that automatically convert session values to the expected type:

```
// Type-safe access with automatic conversion
$userId = Session::getInt('user_id');       // Converts "123" → 123
$price = Session::getFloat('cart_total');   // Converts "19.99" → 19.99
$enabled = Session::getBool('dark_mode');   // Converts "yes" → true
$username = Session::getString('username'); // Converts 123 → "123"

// With defaults for missing values
$limit = Session::getInt('page_limit', 20);
$theme = Session::getString('theme', 'default');
$debug = Session::getBool('debug', false);

// Require values (throw TypeCastException if null/missing)
$requiredId = Session::requireInt('user_id');
$requiredEmail = Session::requireString('email');
```

### Type Conversion Rules

[](#type-conversion-rules)

Values are converted pretty permissively using ([https://github.com/joby-lol/smol-cast)\[smolCast\]](https://github.com/joby-lol/smol-cast)%5BsmolCast%5D), see its readme for detailed rules about what can be converted and how it works.

How It Works
------------

[](#how-it-works)

1. **Reading** - `Session::get()` reads from a cached copy of the session and applies any queued updates
2. **Writing** - `Session::set()`, `Session::increment()`, and `Session::unset()` queue changes without opening the session
3. **Committing** - `Session::commit()` opens the session, applies all updates atomically, and closes it

This approach minimizes session file locking and reduces the window where concurrent requests might conflict.

Advanced: Custom Atomic Updates
-------------------------------

[](#advanced-custom-atomic-updates)

You can create custom atomic update operations by implementing the `SessionUpdate` interface:

```
use Joby\Smol\Session\SessionUpdate;

class AppendToArray implements SessionUpdate
{
    public function __construct(public mixed $value) {}

    public function apply(mixed $current_value): array
    {
        $array = is_array($current_value) ? $current_value : [];
        $array[] = $this->value;
        return $array;
    }

    public function isAbsolute(): bool
    {
        return false; // depends on current value
    }
}

// Use with Session::update()
Session::update('items', new AppendToArray('new_item'));
```

The `isAbsolute()` method indicates whether the update replaces the value entirely (like `SetValue`) or depends on the current value (like `IncrementValue`). Absolute updates enable performance optimizations by discarding previous queued updates for the same key.

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

[](#requirements)

Fully tested on PHP 8.3+, static analysis for PHP 8.1.

License
-------

[](#license)

MIT License - See [LICENSE](LICENSE) file for details.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance76

Regular maintenance activity

Popularity8

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity53

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 ~22 days

Total

4

Last Release

130d ago

PHP version history (2 changes)v1.0.0PHP >=8.4

v1.1.0PHP >=8.3

### Community

Maintainers

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

---

Top Contributors

[![joby-lol](https://avatars.githubusercontent.com/u/856610?v=4)](https://github.com/joby-lol "joby-lol (12 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[firebear/fastprice

Magento 2 FastPrice

113.1k](/packages/firebear-fastprice)

PHPackages © 2026

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