README

A feature-complete Laravel filesystem cache with tagged cache support.

Why Strata?

Laravel's built-in file cache driver has no tag support. Needing tags means opting in for a different driver or having some per env (e.g. prod vs local) logic to interact with the cache differently. Strata closes this gap, it is a drop-in replacement for the default filesystem driver with tagged cache support, isolated locks, and widened support for atomic operations.

Key Features

Drop-in Laravel cache API. Same API and parity with the Laravel's default file driver.
Tag support. Tags are supported natively.
Isolated Atomic locks. Cache::lock() support backed by non-blocking file locks, stored apart from cache system, thus, a flush never releases a lock.
Atomic increment/decrement. These are performed behind a lock, so concurrent calls don't overwrite each other.
Configurable file permissions. You can configure the permission to use for every file and directory Strata creates. It can be useful for certain deployments.

See tools/bench/output for the benchmark (vs Laravel Default Driver) details.

Installation

You can install the package via Composer:

composer require sunchayn/strata

You may publish the package's config with:

php artisan vendor:publish --tag="strata-config"

Requirements

PHP 8.3 or higher.
Laravel 12 or 13.

Setup

Add a store that uses the strata driver to config/cache.php.

'stores' => [
    'strata' => [
        'driver' => 'strata',
    ],
],

Then select it as the default store in your .env file, or use it by name in your code.

CACHE_STORE=strata

Usage

Strata follows the Laravel cache API.

use Illuminate\Support\Facades\Cache;

Cache::store('strata')->put('user:1', $user, 600);
Cache::store('strata')->get('user:1');
Cache::store('strata')->forget('user:1');

Tags

Unlike the Laravel file driver, Strata supports tags.

A tag lets you group cache entries so you can invalidate them all at once, instead of tracking every individual key that needs to expire together. Attach the same tag to any number of values, then flush that one tag when the underlying data changes.

Cache::store('strata')->tags(['books', 'catalog'])->put('books:1', $book, 600);

Cache::store('strata')->get('books:1');

Cache::store('strata')->tags(['books'])->flush();

Note: Tag names must be valid UTF-8.

How tagging and eviction work

Strata does not run anything in the background to keep the cache clean. Everything happens in two steps:

A flush rotates the tag IDs. tags(['books'])->flush() only marks the tag books as flushed adn rotate its internal unique ID. None of the value files stored under it are touched at that moment.
Lazy eviction on reads. Every read first checks the value's expiration and its tags. If the value is expired, or one of its tags was flushed, then the value is evicted and is considered a cache miss.

Note: this design is similar to how the default file driver evicts expired values.

Cached value structure

Part	Content
Line 1	Expiration time
Line 2	Tags, at the time the value was written
Rest of the file	The cached value itself

Scheduling the tag files cleanup

Strata keeps one small file for each tag you have ever used, and never removes it on its own. Schedule the prune command to remove old tag files by adding this to routes/console.php.

use Illuminate\Support\Facades\Schedule;

Schedule::command('strata:prune-stale-tags')->daily();

The command will delete any tag that wasn't re-flushed in the last config('strata.tag_gc_ttl) seconds.

Atomic locks

Strata supports Cache::lock(). Locks are stored in a separate locks directory, so Cache::flush() does not release them.

You can use Cache::flushLocks() to flush all locks them.

Cache::store('strata')->lock('import', 10)->get(function () {
    // ...
});

Atomic Operations

Strata supports cache::add(), similar to the default file driver, to add an item if it doesn't exist (atomically).

It also provides atomic operations support to the following methods:

increment
decrement

Cache::store('strata')->increment('views');
Cache::store('strata')->decrement('stock', 5);

Configuration

Publish the configuration file, then edit config/strata.php.

Key	Default	Purpose
`directory`	`storage/framework/cache/strata`	Root directory of all Strata files.
`tag_gc_ttl`	One month, in seconds	Age after which the prune command deletes a tag file.
`file_permission`	`0o755`	Permission (octal value) of every file and directory Strata creates.

License

Strata is an open-sourced software licensed under the MIT license.

sunchayn / strata

Package info

Security

Statistics