Download the PHP package roddy/stateforge without Composer
On this page you can find all versions of the php package roddy/stateforge. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download roddy/stateforge
More information about roddy/stateforge
Files in roddy/stateforge
Package stateforge
Short Description Elegant, simple state management for Laravel applications.
License MIT
Informations about the package stateforge
StateForge ๐ฅ
Elegant, Isolated State Management for Laravel
StateForge is a powerful, elegant state management package for Laravel that provides isolated, persistent state stores with automatic discovery and multiple persistence options. Built with developer experience in mind, it brings the simplicity of client-side state management to your Laravel applications.
๐ Table of Contents
- Features
- Installation
- Quick Start
- Core Concepts
- Store Lifecycle
- Store Examples
- Events & Hooks
- API Reference
- Persistence Options
- Advanced Usage
- Configuration
- Maintenance
- Best Practices
- Troubleshooting
- FAQ
- Contributing
- License
โจ Features
- ๐ Auto-discovery - Stores automatically discovered and registered
- ๐ User Isolation - Each browser/user gets completely isolated stores
- ๐พ Multiple Persistence - File, cache, session, or in-memory storage
- ๐ฏ Type Safety - Use class references instead of magic strings
- ๐ Persistence Across Sessions - State survives browser restarts
- ๐งฉ Lifecycle Hooks -
onUpdate()for automatic state change handling - ๐ Custom Middlewares - Extend store behavior with middleware arrays
- ๐ญ Event System - Before/after hooks and global events
- ๐ Artisan Commands - Generate stores and manage cleanup
- ๐ฆ Zero Configuration - Works out of the box with sensible defaults
- ๐ Browser Fingerprinting - Fallback identification when cookies are cleared
- ๐ก๏ธ Data Integrity - Checksum verification for persisted data
๐ Installation
Requirements
- PHP 8.0 or higher
- Laravel 9.0 or higher
Install via Composer
Publish Configuration (Optional)
๐ฏ Quick Start
1. Create Your First Store
This creates app/Stores/CounterStore.php with the enhanced architecture:
2. Use in Controller
3. Add Routes
4. Test It Out!
Visit /counter in your browser and see the counter in action! Each browser will have its own isolated counter, and all state changes are automatically logged.
๐ง Core Concepts
Enhanced Store Architecture
StateForge 2.0 introduces a more structured store architecture:
Lifecycle Methods
initializeState()- Define your state properties and methodsmiddlewares()- Return array of custom middlewaresonUpdate()- Called automatically after every state change- Automatic Persistence - Based on
$persistenceType
User Isolation
StateForge automatically isolates stores per user/browser combination:
- โ Same browser, different tabs: Same store
- โ Browser restart: Same store (persisted)
- โ Different browser: Different store
- โ Different device: Different store
Auto-discovery
Stores placed in app/Stores/ are automatically discovered and registered. No manual configuration needed!
๐ Store Lifecycle
Complete Lifecycle Flow
Middleware System
Add custom behavior to your stores:
Automatic onUpdate() Handling
The onUpdate() method is called automatically after every state change:
๐๏ธ Store Examples
Shopping Cart Store with Lifecycle Hooks
User Preferences Store with Automatic Syncing
๐ API Reference
StateForge Facade
Store Instance Methods
๐พ Persistence Options
File Persistence (Default)
- Survives: Browser restarts, system reboots
- Storage: JSON files in
storage/app/private/stateforge - Best for: Long-term data, user preferences, shopping carts
Cache Persistence
- Survives: Browser restarts (with TTL)
- Storage: Laravel cache (Redis, Memcached, etc.)
- Best for: Temporary data, session-like data
Session Persistence
- Survives: Page refreshes only
- Storage: Laravel session
- Best for: Flash data, temporary calculations
No Persistence
- Survives: Current request only
- Storage: Memory
- Best for: Volatile data, calculations
โ๏ธ Configuration
Default Configuration (config/stateforge.php)
๐ Advanced Usage
Using in Livewire Components
Using in Blade Views
Custom Middleware Classes
๐งน Maintenance
Cleanup Commands
Store Creation
๐ Best Practices
Store Design
- Keep stores focused on a single responsibility
- Use descriptive method names
- Leverage
onUpdate()for side effects - Add validation in middlewares
Performance
- Choose appropriate persistence type
- Use cache persistence for frequently accessed data
- Clean up old stores regularly
- Monitor store sizes
Security
- Never store sensitive data without encryption
- Validate all inputs in middlewares
- Use appropriate persistence for data sensitivity
๐ Troubleshooting
Store returns null
Hooks not working
- Ensure you're using the same store instance
- Check that hooks are added before calling methods
- Verify method signatures match
Persistence issues
- Check storage permissions for file persistence
- Verify cache configuration for cache persistence
- Ensure session is configured for session persistence
โ FAQ
How does user isolation work?
StateForge uses a combination of:
- Persistent Cookie: Survives browser restarts
- Browser Fingerprinting: Fallback using user agent, language, etc.
- Client ID: Unique identifier per browser/user combination
Can I use StateForge with SPAs?
Yes! StateForge works perfectly with SPAs. Use the API endpoints to interact with stores from your frontend.
How is data persisted?
Only state data is persisted - methods (closures) are automatically reattached when stores are loaded.
Can I share stores between users?
No, stores are intentionally isolated per user. For shared state, use your database or cache directly.
What's the performance impact?
Minimal. StateForge is optimized for performance with lazy loading and efficient persistence.
Can I use multiple persistence types for different stores?
Yes! Each store can have its own persistence configuration.
๐ License
StateForge is open-sourced software licensed under the MIT license.
๐ค Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Setup
๐ License
StateForge is open-sourced software licensed under the MIT license.
๐ Acknowledgments
- Inspired by modern state management libraries like Zustand and Redux
- Built with the Laravel community in mind
- Thanks to all contributors and users
StateForge - Forge your application state with elegance and power! ๐ฅ
For more information, visit the GitHub repository or join our community.
All versions of stateforge with dependencies
illuminate/support Version ^9.0 || ^10.0 || ^11.0 || ^12.0
illuminate/contracts Version ^9.0 || ^10.0 || ^11.0 || ^12.0