andydefer/jsonl-cache

JSONL Cache

Un système de cache persistant compatible PSR-16 basé sur des fichiers JSONL pour PHP 8.1+

Table des matières

1. Introduction
2. Installation
3. Configuration
4. Concepts fondamentaux
5. Utilisation de base
6. Opérations avancées
7. Gestion du TTL
8. Intégration Laravel
9. Tests
10. Architecture technique
11. Référence technique
12. Licence

Introduction

Le problème

Les caches traditionnels (Redis, Memcached, APC) sont performants mais nécessitent :

• Des services externes supplémentaires
• Une configuration complexe
• Une gestion mémoire spécifique
• Un déploiement particulier

La solution : JSONL Cache

JSONL Cache est un système de cache persistant basé sur des fichiers JSONL (JSON Lines), compatible avec l'interface PSR-16 (Common Interface for Caching Libraries).

Installation

composer require andydefer/jsonl-cache

Pour Laravel, le package s'enregistre automatiquement via son Service Provider.

Publication de la configuration (Laravel)

php artisan vendor:publish --tag=jsonl-cache-config

Configuration

Fichier de configuration

// config/jsonl-cache.php

return [
    // Chemin de base pour les fichiers de cache
    'base_path' => env('JSONL_CACHE_PATH', storage_path('jsonl-cache')),

    // TTL par défaut en secondes (null = pas d'expiration)
    'default_ttl' => (int) env('JSONL_CACHE_TTL', 3600),

    // Nombre de niveaux de hash (1-4)
    'hash_levels' => (int) env('JSONL_CACHE_HASH_LEVELS', 2),

    // Activation/désactivation du cache
    'enabled' => (bool) env('JSONL_CACHE_ENABLED', true),

    // Préfixe ajouté aux clés
    'prefix' => env('JSONL_CACHE_PREFIX', 'cache'),
];

Variables d'environnement

JSONL_CACHE_PATH=/custom/cache/path
JSONL_CACHE_TTL=7200
JSONL_CACHE_HASH_LEVELS=2
JSONL_CACHE_ENABLED=true
JSONL_CACHE_PREFIX=app

Concepts fondamentaux

Une entrée = un fichier JSONL

storage/jsonl-cache/
├── 0/
│   ├── d/
│   │   └── user_123.jsonl
│   └── f/
│       └── session_abc.jsonl
├── e/
│   └── 1/
│       └── product_456.jsonl
└── f/
    └── 3/
        └── config_app.jsonl

Structure d'un fichier cache

{
    "key": "cache_user_123",
    "value": "{\"name\":\"John Doe\",\"email\":\"john@example.com\"}",
    "expires_at": "2026-06-14T15:30:00+00:00",
    "created_at": "2026-06-14T14:30:00+00:00"
}

Organisation par hash MD5

Pourquoi ? Éviter d'avoir trop de fichiers dans un même répertoire (limites du système de fichiers).

Utilisation de base

Instanciation du service

Sans Laravel :

use AndyDefer\JsonlCache\Services\JsonlCacheService;
use AndyDefer\JsonlCache\Config\JsonlCacheConfig;
use AndyDefer\LaravelJsonl\JsonlService;
use AndyDefer\LaravelJsonl\Contexts\JsonlContext;
use AndyDefer\JsonlCache\Strategies\CachePathStrategy;
use AndyDefer\DomainStructures\Services\HydrationService;
use AndyDefer\PhpServices\Services\FileSystemService;

$config = new JsonlCacheConfig(app('config'));
$strategy = new CachePathStrategy('/tmp/cache', 2);
$fs = new FileSystemService();
$hydration = new HydrationService();
$jsonl = new JsonlService($strategy, $fs, new JsonlContext());

$cache = new JsonlCacheService($jsonl, $strategy, $config, $hydration, $fs);

Avec Laravel :

use AndyDefer\JsonlCache\Contracts\JsonlCacheInterface;

class MyController extends Controller
{
    public function __construct(
        private readonly JsonlCacheInterface $cache,
    ) {}

    public function index()
    {
        // Utilisation directe
    }
}

Stocker une valeur

// Stocker avec TTL par défaut (config)
$cache->set('user_123', ['name' => 'John Doe']);

// Stocker pour 1 heure
$cache->set('user_123', $userData, 3600);

// Stocker sans expiration
$cache->set('config_app', $config, null);

Lire une valeur

// Lecture simple
$user = $cache->get('user_123');

// Avec valeur par défaut
$user = $cache->get('user_123', ['name' => 'Guest']);

// Vérifier l'existence
if ($cache->has('user_123')) {
    echo "Cache hit!";
}

Supprimer une valeur

// Supprimer une entrée
$cache->delete('user_123');

// Vider tout le cache
$cache->clear();

Types de valeurs supportés

// Tableau
$cache->set('array_key', ['a' => 1, 'b' => 2]);

// Objet (devient tableau)
$cache->set('object_key', (object) ['name' => 'John']);

// Scalaires
$cache->set('string_key', 'hello');
$cache->set('int_key', 42);
$cache->set('float_key', 3.14);
$cache->set('bool_key', true);
$cache->set('null_key', null);

Opérations avancées

Opérations par lots (Multiple)

// Lecture multiple
$values = $cache->getMultiple(['user_123', 'user_456', 'user_789'], 'default');

// Stockage multiple
$cache->setMultiple([
    'user_123' => ['name' => 'John'],
    'user_456' => ['name' => 'Jane'],
    'user_789' => ['name' => 'Bob'],
], 3600);

// Suppression multiple
$cache->deleteMultiple(['user_123', 'user_456']);

Accès aux données brutes

// Récupérer l'enregistrement complet
$record = $cache->getRecord('user_123');
if ($record) {
    echo $record->key;         // 'cache_user_123'
    echo $record->value;       // '{"name":"John"}'
    echo $record->expires_at;  // DateTimeVO
    echo $record->created_at;  // DateTimeVO
}

// Récupérer le JSON brut
$raw = $cache->getRaw('user_123');
// '{"key":"cache_user_123","value":"{\"name\":\"John\"}","expires_at":"..."}'

Écrasement automatique

La méthode set() écrase automatiquement la valeur existante :

$cache->set('key', 'old value');
$cache->set('key', 'new value'); // Écrase l'ancienne

Gestion du TTL

Différents formats de TTL

// TTL en secondes (int)
$cache->set('key', $value, 3600);     // 1 heure
$cache->set('key', $value, 60);       // 1 minute

// TTL via DateInterval
$cache->set('key', $value, new DateInterval('PT1H'));  // 1 heure
$cache->set('key', $value, new DateInterval('P1D'));   // 1 jour

// Pas de TTL (null = valeur par défaut de la config)
$cache->set('key', $value, null);

// Expiration désactivée (0)
$cache->set('key', $value, 0);

Comportement de l'expiration

// Stocker pour 1 seconde
$cache->set('expiring_key', 'temporary', 1);

// Immédiatement disponible
echo $cache->get('expiring_key'); // 'temporary'

// Attendre l'expiration
sleep(2);

// Plus disponible
echo $cache->get('expiring_key', 'default'); // 'default'
$cache->has('expiring_key'); // false

TTL par défaut

La configuration default_ttl s'applique automatiquement :

// config/jsonl-cache.php
'default_ttl' => 3600,  // 1 heure par défaut

// Utilisation
$cache->set('key', $value); // Expire dans 1 heure
$cache->set('key', $value, 0); // Jamais

Intégration Laravel

Service Provider

Le package enregistre automatiquement :

// Aliases disponibles
$cache = app(JsonlCacheInterface::class);
$cache = app('jsonl-cache');

Exemple dans un contrôleur

<?php

namespace App\Http\Controllers;

use AndyDefer\JsonlCache\Contracts\JsonlCacheInterface;
use App\Models\User;

final class UserController extends Controller
{
    private const CACHE_TTL = 300; // 5 minutes

    public function __construct(
        private readonly JsonlCacheInterface $cache,
    ) {}

    public function show(int $id): JsonResponse
    {
        $cacheKey = "user_{$id}";

        // Tentative de lecture du cache
        $user = $this->cache->get($cacheKey);

        if ($user === null) {
            $user = User::find($id);
            $this->cache->set($cacheKey, $user->toArray(), self::CACHE_TTL);
        }

        return response()->json($user);
    }

    public function update(int $id, Request $request): JsonResponse
    {
        // Mise à jour en base...
        $user = User::find($id);
        $user->update($request->validated());

        // Invalidation du cache
        $this->cache->delete("user_{$id}");

        return response()->json(['message' => 'Updated']);
    }
}

Exemple dans un service

<?php

namespace App\Services;

use AndyDefer\JsonlCache\Contracts\JsonlCacheInterface;

final class WeatherService
{
    private const CACHE_TTL = 1800; // 30 minutes

    public function __construct(
        private readonly JsonlCacheInterface $cache,
        private readonly WeatherApiClient $api,
    ) {}

    public function getForecast(string $city): array
    {
        $cacheKey = "weather_{$city}";

        $forecast = $this->cache->get($cacheKey);
        if ($forecast !== null) {
            return $forecast;
        }

        $forecast = $this->api->fetchForecast($city);
        $this->cache->set($cacheKey, $forecast, self::CACHE_TTL);

        return $forecast;
    }
}

Tests

Tester le cache

<?php

namespace Tests\Unit;

use AndyDefer\JsonlCache\Services\JsonlCacheService;
use Tests\TestCase;

final class CacheTest extends TestCase
{
    private JsonlCacheService $cache;

    protected function setUp(): void
    {
        parent::setUp();
        $this->cache = app(JsonlCacheInterface::class);
    }

    public function test_cache_set_and_get(): void
    {
        $key = 'test_key';
        $value = ['name' => 'John', 'email' => 'john@example.com'];

        $this->cache->set($key, $value);
        $cached = $this->cache->get($key);

        $this->assertEquals($value, $cached);
    }

    public function test_cache_ttl(): void
    {
        $key = 'expiring_key';
        $value = 'temporary';

        $this->cache->set($key, $value, 1);
        $this->assertEquals($value, $this->cache->get($key));

        sleep(2);
        $this->assertNull($this->cache->get($key));
    }

    public function test_cache_delete(): void
    {
        $key = 'to_delete';
        $this->cache->set($key, 'value');
        $this->assertTrue($this->cache->has($key));

        $this->cache->delete($key);
        $this->assertFalse($this->cache->has($key));
    }
}

Architecture technique

Composants principaux

Dépendances

JsonlCacheService
    ├── JsonlService (laravel-jsonl)
    ├── CachePathStrategy
    ├── JsonlCacheConfig
    ├── HydrationService
    └── FileSystemInterface

Flux d'exécution (set)

set($key, $value, $ttl)
    │
    ├── normalizeKey() → ajout préfixe, hash si >64
    ├── getTtlSeconds() → conversion TTL
    ├── createExpiresAt() → DateTimeVO
    ├── json_encode($value) → sérialisation
    ├── Suppression ancien fichier
    ├── Création CacheRecord
    └── jsonl->write() → écriture JSONL

Flux d'exécution (get)

get($key)
    │
    ├── normalizeKey()
    ├── getRecord()
    │   ├── strategy->getFilePathForKey()
    │   ├── fs->exists()
    │   └── jsonl->readAll()
    ├── isExpired() → vérification expiration
    ├── delete() si expiré
    └── json_decode($record->value) → désérialisation

Référence technique

Services

Stratégies

Interfaces

Licence

MIT © Andy Defer