PHPackages pixelee/sagalite - 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. [Utility & Helpers](/categories/utility) 4. / 5. pixelee/sagalite ActiveLibrary[Utility & Helpers](/categories/utility) pixelee/sagalite ================ Lightweight task orchestrator (local sagas) with minimal DB state + JSON journal 00PHP Since Sep 28Pushed 7mo agoCompare [ Source](https://github.com/PixeleeCode/sagalite)[ Packagist](https://packagist.org/packages/pixelee/sagalite)[ RSS](/packages/pixelee-sagalite/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (1)DependenciesVersions (1)Used By (0) SagaLite 🚀 ========== [](#sagalite-) **Une bibliothèque PHP légère pour implémenter le pattern Saga et gérer les transactions distribuées.** SagaLite permet de coordonner des opérations complexes en séquences d'étapes compensables, garantissant la cohérence des données même en cas d'échec partiel. 📋 Description ------------- [](#-description) Le pattern Saga divise une transaction longue en une séquence d'étapes plus petites. Chaque étape possède une action principale et une action de compensation. Si une étape échoue, toutes les étapes précédentes sont automatiquement annulées via leurs compensations. **Cas d'usage typiques :** - Processus de commande e-commerce (réservation stock → paiement → expédition) - Onboarding utilisateur (création compte → envoi email → activation) - Intégrations entre microservices - Workflows métier complexes 🎯 Pourquoi Sagalite ? --------------------- [](#-pourquoi-sagalite-) - **🪶 Léger** : Aucune dépendance externe, focalisé sur l'essentiel - **🔒 Fiable** : Garantit la cohérence des données avec compensation automatique - **🎮 Simple** : API intuitive, démarrage en quelques lignes - **🔧 Flexible** : Support de handlers personnalisés et injection de dépendances - **📊 Traçable** : Journalisation complète des exécutions pour le debugging - **⚡ Performant** : Stockage optimisé avec verrouillage pessimiste - **🧪 Testé** : Suite de tests complète avec 98%+ de couverture 📦 Installation -------------- [](#-installation) ``` composer require pixelee/sagalite ``` **Prérequis :** - PHP 8.2+ - Extension PDO (SQLite, MySQL, PostgreSQL...) 🗄️ Initialisation de la base de données --------------------------------------- [](#️-initialisation-de-la-base-de-données) **Création des tables** SagaLite nécessite des tables spécifiques pour persister l'état des sagas. Pour cela, créer les tables nécessaires à partir du fichier `migrations/001_init.sql` fourni. 🚀 Utilisation rapide -------------------- [](#-utilisation-rapide) **Configuration basique** ``` use Pixelee\SagaLite\Core\SagaManager; use Pixelee\SagaLite\Persistence\PdoSagaStateStore; // Configuration de la base de données $pdo = new PDO('sqlite:saga.db'); $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION); // Lecture et exécution du script de migration // $migrationSql = file_get_contents(__DIR__ . '/migrations/001_init.sql'); // $pdo->exec($migrationSql); // Initialisation du store et manager $store = new PdoSagaStateStore($pdo); $manager = new SagaManager($store); ``` **Définition d'un handler** ``` use Pixelee\SagaLite\StepHandler; use Pixelee\SagaLite\Context; final class CreateUser implements StepHandler { public function __construct( private Users $users ) { } public function handle(Context $context): Context { // Vérification idempotente - évite la re-création if ($context->get('user_created', false)) { return $context; } // Création de l'utilisateur avec les données du contexte $userId = $this->users->create( $context->get('email') ); // Mise à jour du contexte avec le résultat return $context ->with('user_created', true) // Flag indiquant que l'action est faite ->with('user_id', $userId); // ID utilisable dans les étapes suivantes } public function compensate(Context $context): Context { // Annulation seulement si l'action a été faite if ($context->get('user_created', false)) { $this->users->deactivate( $context->get('user_id') ); return $context->with('user_created', false); } return $context; } } ``` **Définition d'une saga** ``` use Pixelee\SagaLite\SagaDefinition; use Pixelee\SagaLite\StepDefinition; use Pixelee\SagaLite\StepPolicy; // Définition de la séquence d'étapes $saga = new SagaDefinition('user_onboarding', [ new StepDefinition( 'create', // Nom de l'étape new CreateUser($users), // Handler principal StepPolicy::retry([2, 5, 10]) // Policy de retry (2s, 5s, 10s) ), new StepDefinition('provision', new ProvisionStorage($storage)), new StepDefinition('welcome', new WelcomeMail($mailer)), ]); ``` **Exécution automatique** ``` try { // Exécution complète de toutes les étapes $result = $manager->execute( $saga, new Context(['email' => 'alice@example.com']) // Contexte initial ); echo "Saga terminée : " . $result->getId(); } catch (Exception $e) { // En cas d'échec, compensation automatique des étapes réussies echo "Échec avec compensation automatique : " . $e->getMessage(); } ``` **Exécution manuelle étape par étape** ``` // Configuration du loader pour l'injection de dépendances $loader = function(string $handlerClass) { return match($handlerClass) { CreateUser::class => new CreateUser($users), ProvisionStorage::class => new ProvisionStorage($storage), WelcomeMail::class => new WelcomeMail($mailer), default => throw new Exception("Handler inconnu : $handlerClass") }; }; // Démarrage de la saga $sagaId = $manager->start($saga, new Context(['email' => 'alice@example.com'])); // Exécution contrôlée étape par étape $manager->resume($sagaId, $loader); // étape 0: create $manager->resume($sagaId, $loader); // étape 1: provision $manager->resume($sagaId, $loader); // étape 2: welcome -> COMPLETED ``` **Policies avancées** ``` // Policy de retry avec backoff exponentiel $exponentialBackoff = StepPolicy::retry([1, 2, 4, 8, 16]); // Timeout personnalisé $withTimeout = StepPolicy::timeout(300); // 5 minutes // Combinaison de policies (si supporté) $criticalStep = new StepDefinition( 'critical-operation', new CriticalHandler(), $exponentialBackoff ); ``` 🔧 Configuration avancée ----------------------- [](#-configuration-avancée) **Configuration du store** ``` $store = new PdoSagaStateStore($pdo, [ 'table_prefix' => 'my_saga_', // Préfixe des tables 'enable_logging' => true, // Activer les logs détaillés 'lock_timeout' => 300, // Timeout de verrouillage 'cleanup_completed_after' => 7200 // Nettoyage après 2h ]); ``` ❌ Ce qu'il ne faut PAS faire ---------------------------- [](#-ce-quil-ne-faut-pas-faire) **🚫 Handlers non-idempotents** ``` // MAUVAIS : peut créer des doublons à chaque retry final class BadHandler implements StepHandler { public function handle(Context $context): Context { $this->db->insert('logs', ['action' => 'done']); // Pas de vérification ! return $context; } } // BON : idempotent avec flag de vérification final class GoodHandler implements StepHandler { public function handle(Context $context): Context { if ($context->get('action_done', false)) { return $context; // Action déjà effectuée } $this->db->insert('logs', ['saga_id' => $context->getSagaId()]); return $context->with('action_done', true); } } ``` **🚫 Modification d'état externe sans flag** ``` // MAUVAIS : pas de trace dans le contexte public function handle(Context $context): Context { $this->externalService->updateStatus($context->get('user_id'), 'active'); return $context; // Pas de flag ! } // BON : toujours marquer les actions public function handle(Context $context): Context { if (!$context->get('external_updated', false)) { $this->externalService->updateStatus($context->get('user_id'), 'active'); } return $context->with('external_updated', true); } ``` **🚫 Compensation destructrice** ``` // MAUVAIS : suppression définitive des données public function compensate(Context $context): Context { $this->users->delete($context->get('user_id')); // Perte de données ! return $context; } // BON : désactivation réversible public function compensate(Context $context): Context { if ($context->get('user_created', false)) { $this->users->markAsInactive($context->get('user_id')); return $context->with('user_created', false); } return $context; } ``` 🐛 Debugging ----------- [](#-debugging) **Inspection du contexte** ``` // Vérifier l'état d'une saga $state = $store->load($sagaId); $context = $state->getContext(); echo "Données actuelles :\n"; foreach ($context->all() as $key => $value) { echo " {$key}: " . json_encode($value) . "\n"; } ``` **Vérification des flags** ``` // Dans un handler, vérifier l'état précédent public function handle(Context $context): Context { echo "État actuel du contexte :\n"; echo "- user_created: " . ($context->get('user_created', false) ? 'oui' : 'non') . "\n"; echo "- user_id: " . $context->get('user_id', 'non défini') . "\n"; // ... logique métier } ``` ### Health Score 16 — LowBetter than 5% of packages Maintenance44 Moderate activity, may be stable Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity13 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/2a253c4a30ec3da1739ef1ff0efa7ba46e3146df76dc690f334706244095f2ce?d=identicon)[Pixelee](/maintainers/Pixelee) --- Top Contributors [![PixeleeCode](https://avatars.githubusercontent.com/u/56721751?v=4)](https://github.com/PixeleeCode "PixeleeCode (2 commits)") ### Embed Badge ![Health badge](/badges/pixelee-sagalite/health.svg) ``` [![Health](https://phpackages.com/badges/pixelee-sagalite/health.svg)](https://phpackages.com/packages/pixelee-sagalite) ``` ### Alternatives [michael-rubel/laravel-formatters This package is a collection of classes you can use to standardize data formats in your Laravel application. It uses the Service Container to easily extend or override the formatter classes. 9491.6k4](/packages/michael-rubel-laravel-formatters) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)