PHPackages alex-kassel/history-engine - 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. alex-kassel/history-engine ActiveLibrary[Caching](/categories/caching) alex-kassel/history-engine ========================== Storage-agnostic history and state navigation engine for PHP 8.2+ and Laravel applications. v1.3.0(today)05↑2900%MITPHPPHP ^8.2 || ^8.3 || ^8.4 Since Aug 11Pushed todayCompare [ Source](https://github.com/alex-kassel/history-engine)[ Packagist](https://packagist.org/packages/alex-kassel/history-engine)[ RSS](/packages/alex-kassel-history-engine/feed)WikiDiscussions main Synced today READMEChangelog (3)Dependencies (7)Versions (7)Used By (0) 🧭 History Engine ================ [](#-history-engine) **Storage-agnostic history navigation, state tracking, and undo/redo pointer engine for PHP 8.2+ and Laravel applications** [Installation](#installation) • [Quick Start](#quick-start) • [UI Predicates & Counters](#ui-predicates--step-counters) • [String Commands](#string-commands) • [Drivers](#drivers) • [Release Gate](RELEASE-GATE.md) • [Changelog](CHANGELOG.md) [![Audit Verified](https://camo.githubusercontent.com/ad42f3e373736ebfc17d1a0f7e929dd1de73284cbeadb5f24488b9dacb7eef9a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f41756469742d56657269666965642d3130623938313f6c6f676f3d736869656c64)](RELEASE-GATE.md) [![Latest Version](https://camo.githubusercontent.com/714022e868d493cd95e572a4c85c1167ea18e591f53bc8eb55255e31f514c65e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c65782d6b617373656c2f686973746f72792d656e67696e653f636f6c6f723d663539653062266c6f676f3d7061636b6167697374266c6f676f436f6c6f723d7768697465)](https://packagist.org/packages/alex-kassel/history-engine) [![Laravel Support](https://camo.githubusercontent.com/32bb20867c064c55c8d525a65a804cf541a083615e3e1810d8098774901ac762/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d3131253230253743253230313225323025374325323031332d6666326432303f6c6f676f3d6c61726176656c266c6f676f436f6c6f723d7768697465)](https://laravel.com) [![PHP Support](https://camo.githubusercontent.com/efb9e9ab96e9febd681c962354b111daa4f2cddccc85b9571e7452145877aeb2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322b2d3737376262343f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](https://php.net) [![PHPStan Level Max](https://camo.githubusercontent.com/12a851c30b0a4a96268ec381d89ec543bf69a5d6f5141ae80ee15422cf410420/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048505374616e2d4c6576656c2532304d61782d3862356366363f6c6f676f3d706870266c6f676f436f6c6f723d7768697465)](RELEASE-GATE.md) --- **History Engine** provides a clean, storage-agnostic state history navigation engine for Laravel applications. It manages linear item histories, navigation pointers, branching truncation, and undo/redo operations across multiple persistent backends (**Session**, **Cache**, **Redis**). --- Key Features ------------ [](#key-features) - **Multi-Backend Storage:** Seamlessly switch between `session`, `cache`, and `redis` storage drivers, or register custom stores via `HistoryEngine::extend()`. - **Isolated Scopes:** Create isolated history stacks per user session, workflow step, or UI component via `HistoryEngine::engine('scope_name')`. - **Bidirectional Step Counters:** Query available undo/redo steps (`backCount()`, `forwardCount()`) for browser-like button badges. - **UI Predicates & Peek:** Instant status checks (`canStepBack()`, `canStepForward()`, `isAtStart()`, `isAtEnd()`) and non-destructive peek methods (`peekBack()`, `peekForward()`). - **Frontend DTO Snapshot:** Export complete state via `snapshot()` (`HistorySnapshot` implementing `JsonSerializable` and `Arrayable`) for Vue, React, Livewire, and Inertia. - **Automatic Branch Truncation:** Recording a new item while positioned in the middle of history automatically truncates future forward steps (browser-like navigation semantics). - **Consecutive Deduplication:** Automatically avoids recording redundant duplicate entries when the current pointer already matches the payload. - **String Command DSL:** Quick navigation with shorthand command syntax (``, ``, `3`, `index`, `@`). - **First-Class IDE DX:** 100% strictly typed API and Facade autocomplete annotations passing PHPStan at level Max. --- Requirements ------------ [](#requirements) - **PHP:** 8.2+ (tested on 8.2, 8.3, 8.4) - **Laravel Framework:** 11.x | 12.x | 13.x --- Installation ------------ [](#installation) Install the package via Composer: ``` composer require alex-kassel/history-engine ``` The Service Provider and `HistoryEngine` facade will register automatically via Laravel package discovery. Optionally publish the configuration file: ``` php artisan vendor:publish --tag="history-engine-config" ``` --- Configuration ------------- [](#configuration) The published `config/history-engine.php` allows setting the default store, TTL, and driver settings: ``` return [ // Default driver: session | cache | redis 'default' => env('HISTORY_ENGINE_DRIVER', 'session'), // Key prefix used across storage drivers 'prefix' => env('HISTORY_ENGINE_PREFIX', 'history_engine:'), 'drivers' => [ 'session' => [ 'class' => \AlexKassel\HistoryEngine\Stores\SessionHistoryStore::class, ], 'cache' => [ 'class' => \AlexKassel\HistoryEngine\Stores\CacheHistoryStore::class, 'store' => env('HISTORY_ENGINE_CACHE_STORE', null), 'ttl' => env('HISTORY_ENGINE_TTL', null), // seconds (null = forever) ], 'redis' => [ 'class' => \AlexKassel\HistoryEngine\Stores\RedisHistoryStore::class, 'connection' => env('HISTORY_ENGINE_REDIS_CONNECTION', null), 'ttl' => env('HISTORY_ENGINE_TTL', null), // seconds (null = forever) ], ], ]; ``` --- Quick Start ----------- [](#quick-start) ### 1. Basic Recording & Navigation [](#1-basic-recording--navigation) ``` use AlexKassel\HistoryEngine\Facades\HistoryEngine; // Direct facade usage with default scope, or specify custom scope HistoryEngine::record('filter:audi', 'search-filters'); HistoryEngine::record('filter:audi-q4', 'search-filters'); HistoryEngine::record('filter:audi-q4-2024', 'search-filters'); // Inspect state HistoryEngine::getCurrent('search-filters'); // 'filter:audi-q4-2024' HistoryEngine::getPointer('search-filters'); // 2 HistoryEngine::getAll('search-filters'); // ['filter:audi', 'filter:audi-q4', 'filter:audi-q4-2024'] // Navigate backwards & forwards HistoryEngine::stepBack(1, 'search-filters'); // 'filter:audi-q4' HistoryEngine::stepBack(1, 'search-filters'); // 'filter:audi' HistoryEngine::stepForward(1, 'search-filters'); // 'filter:audi-q4' // Jump directly to boundaries or indices HistoryEngine::goToStart('search-filters'); // 'filter:audi' HistoryEngine::goToEnd('search-filters'); // 'filter:audi-q4-2024' HistoryEngine::goToIndex(1, 'search-filters'); // 'filter:audi-q4' ``` ### 2. Method Chaining [](#2-method-chaining) ``` $engine = HistoryEngine::engine('wizard') ->clear() ->record('step-1') ->record('step-2') ->record('step-3'); ``` --- UI Predicates & Step Counters --------------------------------- [](#ui-predicates--step-counters) Perfect for rendering interactive Back/Forward navigation in Blade, Livewire, Inertia, Vue, or React: ``` $engine = HistoryEngine::engine('catalog'); $engine->canStepBack(); // bool (true if pointer > 0) $engine->canStepForward(); // bool (true if forward steps exist) $engine->backCount(); // int (e.g. 3 steps available backward) $engine->forwardCount(); // int (e.g. 2 steps available forward) $engine->isAtStart(); // bool (true if at first item) $engine->isAtEnd(); // bool (true if at last item) $engine->isEmpty(); // bool $engine->count(); // int (total history items, implements \Countable) // Peek surrounding items without moving pointer $previous = $engine->peekBack(); // 'step-2' (pointer remains unchanged!) $next = $engine->peekForward(); // 'step-4' ``` ### 3. Frontend JSON Snapshot [](#3-frontend-json-snapshot) ``` // In a Laravel Controller / Inertia response: return response()->json(HistoryEngine::engine('filters')->snapshot()); // Output JSON: // { // "scope": "filters", // "current": "audi-q4", // "pointer": 2, // "total": 5, // "items": ["all", "audi", "audi-q4", "audi-q4-2024", "audi-q4-ev"], // "can_step_back": true, // "can_step_forward": true, // "back_count": 2, // "forward_count": 2, // "is_at_start": false, // "is_at_end": false, // "is_empty": false // } ``` --- String Commands --------------- [](#string-commands) The package includes a concise command DSL for driving navigation from UI requests, URL query parameters, or keyboard shortcuts: ``` // Back / Forward single step HistoryEngine::applyCommand('', 'wizard'); // Step forward // Multi-step jumps HistoryEngine::applyCommand('3', 'wizard'); // Step forward 3 items // Jump to start / end HistoryEngine::applyCommand('>', 'wizard'); // Go to end (latest item) // Jump to specific 0-based index HistoryEngine::applyCommand('2', 'wizard'); // Go to index 2 // Clear history stack HistoryEngine::applyCommand('@', 'wizard'); ``` --- Drivers ------- [](#drivers) ### Using Specific Drivers Directly [](#using-specific-drivers-directly) ``` // Use Redis driver explicitly for long-lived background jobs $redisEngine = HistoryEngine::driver('redis'); // Register custom storage drivers HistoryEngine::extend('database', function ($app, array $config) { return new MyDatabaseHistoryStore(); }); ``` --- Testing ------- [](#testing) Run unit and integration test suites: ``` # Run PHPUnit tests php artisan test -c packages/alex-kassel/history-engine/phpunit.xml # Run PHPStan static analysis at level max vendor/bin/phpstan analyse packages/alex-kassel/history-engine/src --level=max ``` --- Changelog --------- [](#changelog) Please see [CHANGELOG.md](CHANGELOG.md) for more information on what has changed recently. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [Security Policies](https://github.com/alex-kassel/history-engine/security/policy) on how to report vulnerabilities. License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 45 — FairBetter than 91% of packages Maintenance100 Actively maintained with recent releases Popularity5 Limited adoption so far Community6 Small or concentrated contributor base Maturity59 Maturing project, gaining track record 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. ### Release Activity Cadence Every ~76 days Recently: every ~94 days Total 6 Last Release 0d ago PHP version history (3 changes)v1.0.0PHP ^8.1 v1.1.0PHP ^8.3 v1.2.0PHP ^8.2 || ^8.3 || ^8.4 ### Community Maintainers ![](https://www.gravatar.com/avatar/f11bb887e4e2c6eb34ec331939e34acf86591a4a2cafce3e9e7bbe9aeb950708?d=identicon)[Alexander Macenko](/maintainers/Alexander%20Macenko) --- Top Contributors [![alex-kassel](https://avatars.githubusercontent.com/u/144229516?v=4)](https://github.com/alex-kassel "alex-kassel (10 commits)") --- Tags historylaravelnavigationlaravelrediscachehistorysessionnavigation ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/alex-kassel-history-engine/health.svg) ``` [![Health](https://phpackages.com/badges/alex-kassel-history-engine/health.svg)](https://phpackages.com/packages/alex-kassel-history-engine) ``` ### Alternatives [propaganistas/laravel-disposable-email Disposable email validator 6023.2M7](/packages/propaganistas-laravel-disposable-email)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k16.3M158](/packages/laravel-pulse)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 46273.9k](/packages/harris21-laravel-fuse)[psalm/plugin-laravel Psalm plugin for Laravel 3345.4M354](/packages/psalm-plugin-laravel)[iazaran/smart-cache Smart Cache is a caching optimization package designed to enhance the way your Laravel application handles data caching. It intelligently manages large data sets by compressing, chunking, or applying other optimization strategies to keep your application performant and efficient. 21114.2k](/packages/iazaran-smart-cache)[illuminate/routing The Illuminate Routing package. 1239.4M3.7k](/packages/illuminate-routing) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)