pixelee / sagalite
Lightweight task orchestrator (local sagas) with minimal DB state + JSON journal
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- phpunit/phpunit: ^12.3
This package is auto-updated.
Last update: 2025-09-28 15:44:41 UTC
README
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
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 ?
- 🪶 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
composer require pixelee/sagalite
Prérequis :
- PHP 8.2+
- Extension PDO (SQLite, MySQL, PostgreSQL...)
🗄️ 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
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 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
🚫 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
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 }