laravel-cache-contract maintained by uslanozan
laravel-cache-contract
Pre-release. The API can still change before 1.0. There is no tagged release yet; the first one is
v0.1.0.
A Laravel package that puts every cache entry in a project under one central, reviewable contract, on top of Laravel's own cache and Redis.
| Feature | Status | |
|---|---|---|
| Definitions | Each cache entry type is defined once in PHP, with a description, a TTL and typed parameters. Unknown IDs and wrong parameters fail loudly. | ✅ |
| Keys | Keys are generated from the definition, its parameters and the context (tenant, locale…), never typed by hand. | ✅ |
| Runtime API | CacheContract::remember(), get, has, put, refresh, forget; a cached null, false or 0 is a hit. |
✅ |
| Model cache | ModelCache::for(User::class)->find(5) and findMany() without per-model classes. Models with global scopes (e.g. a tenant) need the tenant in the context; see Model cache. |
✅ |
| Discovery | cache-contract:list and cache-contract:inspect, with "did you mean" suggestions for a mistyped ID. |
✅ (warnings for similar definitions: planned) |
| Scanner | cache-contract:scan lists every cache call in a codebase with its file, line and how much of its key can be read. |
✅ |
| Invalidation | Models with HasCache clear their entries after a change is committed, a definition's invalidated_by clears all its entries when a listed model changes, and CacheContract::flushTag() clears every definition with a tag, all with generation counters; see Model cache and Definitions. |
✅ |
| Enforcement | Lint and PHPStan rules for CI. | 🗓️ planned |
Quick example
// config/cache-contract.php
'definitions' => [
'user' => [
'profile' => [
'purpose' => 'profile',
'type' => 'array',
'params' => ['user_id' => 'int'],
'ttl' => '1 hour',
'description' => 'Profile page data.',
],
],
],
use Uslanozan\CacheContract\Facades\CacheContract;
$profile = CacheContract::remember('user.profile', ['user_id' => 42], fn () => $this->loadProfile(42));
// key: cc:user:profile:v1:user_id=42
Requirements
- PHP 8.3.36+, 8.4.27+ or 8.5.12+ (earlier releases have a known zero-day)
- Laravel 11.44.2+, 12.0.1+ or 13 (on PHP 8.5: Laravel 12.40+ or 13)
- Redis 6.2+ as the cache store, with phpredis or predis 2.3+ (no Redis Cluster)
Laravel 11 is end of life and every 11.x release has known, unpatched security advisories. The package supports it because existing projects still run it, but upgrading to Laravel 12.69+ or 13.30+ (the lowest releases with no known advisories as of October 2026) is strongly recommended. See ADR 0003.
Installation
The package is not on Packagist yet, so install it from GitHub. There is no
tag yet either, so require dev-develop; once v0.1.0 is tagged, use ^0.1.
// composer.json
"repositories": [
{ "type": "vcs", "url": "https://github.com/uslanozan/laravel-cache-contract" }
]
composer require uslanozan/laravel-cache-contract:dev-develop
php artisan vendor:publish --tag=cache-contract-config
Details: Installation.
Documentation
The user guide covers installation, definitions, the
runtime API, the model cache, the commands and production settings. The
decisions behind the design are in docs/adr/, and the
changelog lists what each release adds.
Contributing
See CONTRIBUTING.md.