Weave Code
Verbs Laravel Package
hirethunk/verbs
Verbs is a Laravel-friendly event sourcing package for PHP artisans that keeps the benefits of event sourcing while cutting boilerplate and jargon. Model behavior as verbs, record events, and build projections with a clean, approachable API.
Verbs is an event sourcing package for PHP artisans
Frequently asked questions about Verbs
- How do I get started with Verbs in a Laravel project?
- Install via Composer with `composer require hirethunk/verbs`, then publish migrations (`php artisan vendor:publish --tag=verbs-migrations`) to create `verb_events` and `verb_snapshots` tables. Start by defining a `State` class for your aggregate (e.g., `OrderState`) and model behavior as verbs like `place()` or `cancel()`. Use `Verbs::commit()` instead of `Model::save()` to persist events.
- What Laravel versions does Verbs support?
- Verbs officially supports Laravel 10–13. While it may work with Laravel 9.x, test thoroughly as some features (e.g., Livewire integration) rely on newer Laravel APIs. Check the [release notes](https://github.com/hirethunk/verbs/releases) for version-specific changes.
- Can I use Verbs with Livewire for real-time updates?
- Yes, Verbs integrates natively with Livewire. Use the `commitBeforeRender` hook in your Livewire component to ensure events are committed before rendering. This is useful for real-time dashboards or collaborative features where immediate feedback is critical.
- How does Verbs handle performance with large event histories?
- Verbs supports snapshots to reduce replay time, but they increase storage overhead. Enable snapshots via `Verbs::withSnapshots()` and configure snapshot frequency in your `State` class. For high-concurrency scenarios, use optimistic locking (via `last_event_id`) and retry logic for conflicts.
- Is Verbs suitable for a brownfield Laravel project with existing Eloquent models?
- Verbs works best in greenfield projects, but you can adopt it incrementally. Wrap existing Eloquent models in `State` classes and use `Verbs::fire()` alongside traditional events. Start with high-value domains (e.g., orders or payments) to minimize disruption.
- How do I test event sourcing logic with Verbs?
- Verbs includes Wormhole for time travel testing and mock event stores. Use `Verbs::replay()` to simulate event replays in feature tests, and leverage Pest/PHPUnit for unit tests. Example: `Verbs::replay([new OrderPlaced()])->assertStateEquals(new OrderState())`.
- What databases does Verbs support, and how are events stored?
- Verbs supports MySQL and PostgreSQL, storing events as JSON in the `verb_events` table. Snapshots are stored separately in `verb_snapshots`. No schema migrations are required for events—Verbs handles serialization automatically, but ensure your database supports JSON operations.
- How does Verbs compare to Spatie’s EventSauce or custom CQRS solutions?
- Verbs is more opinionated than Spatie’s EventSauce, forcing a 'verb-first' approach that simplifies CQRS/ES adoption. It includes built-in state management and Livewire hooks, but lacks the maturity and community of EventSauce. For full control, you can implement a custom `EventStore` via Verbs’ interface.
- Can I use Verbs with Laravel Queues for async event processing?
- Yes, dispatch events asynchronously using Laravel Queues. Verbs events are serializable, so you can queue them like any other job. Example: `Verbs::commit()->dispatch(new HandleOrderPlaced())`. This works seamlessly with Laravel’s queue drivers (database, Redis, etc.).
- What are the risks of using Verbs for immutable event sourcing?
- Events are immutable, but state mutations must be explicit to avoid unintended side effects. Model your verbs carefully to ensure atomicity. Use snapshots sparingly—they simplify reads but can obscure the event history. Always test replay scenarios to catch inconsistencies early.
Weaver
How can I help you explore Laravel packages today?