Weave Code
Verbs Laravel Package
hirethunk/verbs
Verbs is a PHP event sourcing package for Laravel artisans. It delivers the benefits of event sourcing while minimizing boilerplate and jargon, making it simpler to model behavior and build systems by thinking in actions (verbs) instead of nouns.
Verbs is an event sourcing package for PHP/Laravel artisans that keeps the power of event-driven architecture while stripping away boilerplate and jargon. It encourages you to model behavior as verbs (actions) rather than drowning in “nouns,” making event sourcing approachable and productive.
Build auditable systems with a clean, developer-friendly workflow and a strong focus on clarity—ideal for teams who want the benefits of event sourcing without the usual ceremony.
- Low-boilerplate event sourcing designed for PHP projects
- A verb-first mental model for modeling business behavior
- Auditability through a clear history of events
- Docs-first experience with thorough guides and examples
- Built for artisan-friendly development and maintainable code
Frequently asked questions about Verbs
- How does Verbs differ from traditional event sourcing libraries for Laravel?
- Verbs strips away complexity by focusing on **verbs (actions)** instead of nouns (entities), reducing boilerplate like event handlers and state managers. It uses Laravel attributes (e.g., #[StateId], #[AppliesToState]) to automate bindings, while still enforcing event-driven architecture. Unlike generic libraries, it’s optimized for PHP artisans with clear docs and Artisan commands for scaffolding.
- Can I use Verbs with Laravel 10+? What about older versions?
- Verbs is fully compatible with **Laravel 10+** and leverages PHP 8.1+ features like attributes for cleaner syntax. Older versions (e.g., Laravel 9) may work but lack full attribute support, requiring manual configuration. Check the [docs](https://verbs.thunk.dev/) for version-specific guidance.
- How do I model a simple workflow (e.g., order processing) with Verbs?
- Define **events as verbs** (e.g., `OrderCreated`, `PaymentProcessed`) and **states as snapshots** of the system. Use attributes like `#[AppliesToState(Order::class)]` to link events to states. The `handle()` method in events updates the state, while `apply()` ensures idempotency. Example: `verbs:event OrderCreated` generates the event class skeleton.
- Does Verbs support event replay for debugging or auditing?
- Yes, Verbs includes replay capabilities via the `unlessReplaying()` guard and `#[Once]` attribute to prevent duplicate processing. To replay events, use the `Verbs::replay()` method or trigger replays via Artisan (`php artisan verbs:replay`). For debugging, log events with metadata (e.g., `team_id`) to trace state changes.
- How does Verbs handle database storage? Can I use PostgreSQL?
- Verbs abstracts storage behind a clean API and supports **PostgreSQL and MySQL** out-of-the-box. It stores events in a dedicated table (e.g., `events`) and states in another (e.g., `states`), with migrations included. For large-scale systems, configure snapshot policies to balance storage vs. replay performance.
- What if my state validation fails during event processing?
- Verbs validates states via the `validate()` method in event handlers. If validation fails, the event is rejected, and the state remains unchanged. Unlike some libraries, it **does not auto-rollback**—you must design idempotent events or use middleware to handle failures. Log errors with `#[Metadata]` for debugging.
- Can I mix Verbs with Eloquent models, or is it all-in?
- Verbs supports **hybrid models**: states can coexist with Eloquent, allowing gradual adoption. Use the `#[StateId]` attribute to link states to Eloquent models, and leverage `handle()` to persist changes. This is ideal for migrating legacy systems to event sourcing incrementally.
- Are there performance concerns with storing every event?
- Storing every event can bloat your database, but Verbs mitigates this with **snapshot policies** (e.g., store every 100th event). For read-heavy apps, use projections or materialized views. Index `state_id` and `event_type` in your event table to optimize replays and queries.
- How do I test Verbs in my Laravel application?
- Test events and states by mocking the `Verbs` facade or using `Verbs::fake()` to intercept events. Assert state changes with `Verbs::assertStateWasUpdated()` or replay events in tests. For complex workflows, test edge cases like failed validations or concurrent events using Laravel’s `refreshDatabase()` or database transactions.
- What alternatives to Verbs exist for Laravel event sourcing?
- Alternatives include **Laravel Event Sourcing** (generic but verbose), **ProophEventStore** (PHP-focused but heavier), and **Axon Framework** (Java-inspired). Verbs stands out for its **Laravel-native syntax**, low ceremony, and verb-first approach. If you need sagas or distributed transactions, consider **Axon** or **Prooph**, but they require more setup.
Weaver
How can I help you explore Laravel packages today?