PHP download

Download the PHP package andydefer/laravel-jsonl without Composer

On this page you can find all versions of the php package andydefer/laravel-jsonl. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

Table of contents
Download andydefer/laravel-jsonl
More information about andydefer/laravel-jsonl
Files in andydefer/laravel-jsonl

Vendor andydefer
Package laravel-jsonl
Short Description JSONL storage service for Laravel - write, read, query, and clean JSON Lines files with custom path strategies
License MIT

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:

If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.

Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
To use Composer is sometimes complicated. Especially for beginners.
Composer needs much resources. Sometimes they are not available on a simple webspace.
If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.

Please rate this library. Is it a good library?

Example code of andydefer/laravel-jsonl

Informations about the package laravel-jsonl

Laravel JSONL - Documentation complète

Table des matières

Introduction
Installation
Architecture et concepts
Les stratégies de chemin
Utilisation de base
Opérations avancées
Buffer d'écriture
Verrouillage concurrentiel
Nettoyage des données
Configuration
Bonnes pratiques
Exemples complets
API Reference
Dépannage

Introduction

Laravel JSONL est un package de stockage de données au format JSON Lines (JSONL) pour PHP 8.1+. Chaque ligne est un JSON valide, ce qui le rend idéal pour :

Logs structurés : Journalisation d'événements avec recherche par date/heure
Cache persistant : Stockage de données avec expiration
Métriques : Collecte de données temps réel
Audit trails : Traçabilité immuable des actions

Pourquoi JSONL plutôt que JSON classique ?

Critère	JSON classique	JSONL
Ajout de données	Doit réécrire tout le fichier	Simple append
Streaming	Impossible (doit tout charger)	Possible ligne par ligne
Recherche	Doit parser tout le fichier	Streaming + filtrage
Corruption	Fichier complet inutilisable	Une ligne corrompue n'affecte pas les autres
Parallélisme	Difficile (lock sur tout le fichier)	Possible par ligne

Installation

Prérequis :

PHP 8.1 ou supérieur
Composer
(Optionnel) Laravel 10, 11 ou 12 pour l'intégration automatique

Sans Laravel (PHP pur)

Avec Laravel

Le package s'enregistre automatiquement via le Service Provider. Publiez la configuration :

Architecture et concepts

Le pattern Stateless Service

Le JsonlService est conçu comme un service stateless. Tout l'état (verrous actifs, buffer d'écriture) est déporté dans un JsonlContext injecté. Cette architecture offre plusieurs avantages :

Testabilité : On peut isoler et tester chaque composant indépendamment
Prévisibilité : Pas d'effets de bord cachés entre appels
Concurrence : Chaque contexte peut être isolé par thread/requête

Records

Les Records sont des objets immutables qui représentent les données à stocker. Ils ne contiennent aucune logique métier - uniquement des propriétés.

LogJsonlRecord - Pour la journalisation

CacheJsonlRecord - Pour le cache

Stratégies de chemin

Les stratégies déterminent où les fichiers sont stockés. Le service ne sait pas où ranger les données - il délègue cette décision à la stratégie.

Les stratégies de chemin

Pourquoi des stratégies ?

L'organisation des fichiers dépend du cas d'usage :

Besoin	Organisation idéale
Logs	Par date/heure (recherche temporelle)
Cache	Par hash de clé (accès direct O(1))

Le package fournit deux stratégies prêtes à l'emploi, et vous pouvez créer les vôtres.

TemporalPathStrategy (pour les logs)

Structure : {basePath}/{YYYY-MM-DD}/{HH}.jsonl

Avantages :

Recherche par intervalle de temps rapide
Nettoyage facile par date (suppression de dossiers entiers)
Streaming par jour/heure
Pas besoin d'index, la structure EST l'index

Exemple :

KeyBasedPathStrategy (pour le cache)

Structure : {basePath}/{hash[0]}/{hash[1]}/{sanitized_key}.jsonl

Comment ça marche :

md5('user_123') = e10adc3949ba59abbe56e057f20f883e
Niveaux de hash : e → 1
Chemin final : /cache/e/1/user_123.jsonl

Avantages :

Accès direct O(1) - on sait exactement quel fichier lire
Répartition équilibrée (le hash disperse naturellement)
Pas de scanning inutile
Suppression rapide par clé

Exemple :

Créer sa propre stratégie

Implémentez JsonlPathStrategyInterface :

Utilisation de base

Écrire un log

Résultat dans le fichier :

Écrire une entrée de cache

Lire un fichier

Rechercher dans un fichier

Opérations avancées

Écriture par lots (batch)

Plus efficace que des écritures individuelles pour de gros volumes :

Écriture avec verrouillage

Par défaut, write() et writeBatch() utilisent un verrouillage exclusif (flock). Désactivez-le pour les environnements mono-processus :

Recherche sur plusieurs fichiers

Utilisation du contexte de traitement

Le JsonlProcessingContext suit l'état d'une opération :

Buffer d'écriture

Le buffer accumule les entités en mémoire avant de les écrire sur le disque, réduisant ainsi les opérations I/O.

Activer le buffer

Utilisation

Callback de flush

Désactiver le buffer

Verrouillage concurrentiel

Le package utilise flock pour garantir l'intégrité des données en environnement concurrent.

Verrouillage automatique

Les méthodes write() et writeBatch() utilisent un verrou par défaut :

Verrouillage manuel

Exécution atomique

Nettoyage des données

Nettoyage par âge (fichiers entiers)

Nettoyage par pattern

Nettoyage des entrées expirées (cache)

Dry run - Simulation avant suppression

Vider complètement un répertoire

Configuration

Variables d'environnement

Fichier de configuration Laravel

Bonnes pratiques

1. Utilisez la stratégie adaptée à votre besoin

Cas d'usage	Stratégie recommandée
Logs, événements, audits	`TemporalPathStrategy`
Cache, sessions	`KeyBasedPathStrategy`

2. Activez le buffer pour les écritures fréquentes

3. Utilisez les queries typées

4. Structurez vos payloads

5. Gérez les exceptions

6. Nettoyez régulièrement

Exemples complets

Application de logging complète

Service de cache persistant

Intégration Laravel

API Reference

Interfaces

Interface	Méthodes principales
`JsonlWriterInterface`	`write()`, `writeBatch()`, `writeBuffered()`, `flushBuffer()`
`JsonlReaderInterface`	`readAll()`, `readLineByLine()`, `search()`, `searchMultiple()`
`JsonlCleanerInterface`	`cleanOlderThan()`, `cleanExpired()`, `cleanByPattern()`, `dryRun()`, `clear()`
`JsonlLockInterface`	`acquire()`, `release()`, `executeWithLock()`, `isLocked()`
`JsonlPathStrategyInterface`	`getFilePath()`, `getFilesToScan()`, `getBaseDirectory()`

Classes principales

Classe	Rôle
`JsonlService`	Service principal (stateless)
`JsonlContext`	État du service (locks, buffer)
`LogJsonlRecord`	Record pour logs
`CacheJsonlRecord`	Record pour cache
`TemporalPathStrategy`	Stratégie temporelle
`KeyBasedPathStrategy`	Stratégie par clé
`JsonlProcessingContext`	Contexte de traitement
`TemporalLogQueryRecord`	Query pour logs temporels
`CacheKeyQueryRecord`	Query pour cache par clé

Exceptions

Exception	Description
`JsonlException`	Exception de base
`JsonlLockException`	Problème de verrouillage

Dépannage

Erreur : "Unsupported record type"

La stratégie attend un type spécifique de Record.

Solution : Utilisez le bon Record avec la bonne stratégie :

TemporalPathStrategy → LogJsonlRecord
KeyBasedPathStrategy → CacheJsonlRecord

Erreur : "Timeout acquiring lock"

Un autre processus maintient le verrou trop longtemps.

Solution :

Augmentez le timeout : $service->acquire($path, timeout: 10)
Vérifiez les processus zombies
Nettoyez les fichiers .lock orphelins

Les fichiers ne sont pas trouvés par `cleanExpired()`

Le pattern glob ** n'est pas supporté sur certains systèmes.

Solution : Le package utilise RecursiveIterator, compatible tous systèmes.

Performance lente avec beaucoup de petits fichiers