PHPackages                             andydefer/jsonl-cache - 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. [Caching](/categories/caching)
4. /
5. andydefer/jsonl-cache

ActiveLibrary[Caching](/categories/caching)

andydefer/jsonl-cache
=====================

PSR-16 compatible JSONL-based cache system with key-based path strategy

v0.3.10(2w ago)0351MITPHPPHP ^8.2

Since Jun 14Pushed 3d agoCompare

[ Source](https://github.com/andydefer/jsonl-cache)[ Packagist](https://packagist.org/packages/andydefer/jsonl-cache)[ RSS](/packages/andydefer-jsonl-cache/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (12)Versions (14)Used By (1)

JSONL Cache
===========

[](#jsonl-cache)

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

[![PHP Version](https://camo.githubusercontent.com/83dd395020c37276225039739320f6c8e7e99963ab21ee3d09282cb48dad2a60/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e312532422d626c7565)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/ba69236eb9bfe25effcb7eb44086de41847364b41b47c2e3f6c3975cd2653974/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31322e7825323025374325323031332e7825323025374325323031342e7825323025374325323031352e782d626c7565)](https://laravel.com)[![License](https://camo.githubusercontent.com/5caa455d8debc46fb23abbadb45a733a937f3910a73fc875c2f7820468e1bb54/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e)](LICENSE)

---

Table des matières
------------------

[](#table-des-matières)

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Concepts fondamentaux](#concepts-fondamentaux)
5. [Utilisation de base](#utilisation-de-base)
6. [Opérations avancées](#op%C3%A9rations-avanc%C3%A9es)
7. [Gestion du TTL](#gestion-du-ttl)
8. [Intégration Laravel](#int%C3%A9gration-laravel)
9. [Tests](#tests)
10. [Architecture technique](#architecture-technique)
11. [Référence technique](#r%C3%A9f%C3%A9rence-technique)
12. [Licence](#licence)

---

Introduction
------------

[](#introduction)

### Le problème

[](#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

[](#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).

ProblèmeSolution JSONL CacheDépendance à Redis/MemcachedStockage fichiers - 100% PHPConfiguration complexeZéro configuration, prêt à l'emploiPerte de données au redémarragePersistance automatiquePas de TTL natifSupport complet du Time To LiveInterface propriétairePSR-16 : changez de driver sans modifier votre code---

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

[](#installation)

```
composer require andydefer/jsonl-cache
```

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

### Publication de la configuration (Laravel)

[](#publication-de-la-configuration-laravel)

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

---

Configuration
-------------

[](#configuration)

### Fichier de 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

[](#variables-denvironnement)

```
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
---------------------

[](#concepts-fondamentaux)

### Une entrée = un fichier JSONL

[](#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

[](#structure-dun-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

[](#organisation-par-hash-md5)

NiveauDescriptionExemple1Premier caractère du MD5`e`2Second caractère du MD5`1`FichierClé nettoyée`user_123.jsonl`**Pourquoi ?** Éviter d'avoir trop de fichiers dans un même répertoire (limites du système de fichiers).

---

Utilisation de base
-------------------

[](#utilisation-de-base)

### Instanciation du service

[](#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-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

[](#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-valeur)

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

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

### Types de valeurs supportés

[](#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-avancées)

### Opérations par lots (Multiple)

[](#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

[](#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

[](#é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
--------------

[](#gestion-du-ttl)

### Différents formats de 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

[](#comportement-de-lexpiration)

```
// 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

[](#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
-------------------

[](#intégration-laravel)

### Service Provider

[](#service-provider)

Le package enregistre automatiquement :

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

### Exemple dans un contrôleur

[](#exemple-dans-un-contrôleur)

```