Verbs Laravel Package

Technical Evaluation

Architecture Fit

• Event Sourcing Paradigm: Verbs aligns well with Laravel applications requiring event-driven architecture, auditability, or temporal queries. Its "verb-first" approach (actions over nouns) simplifies CQRS/ES adoption by abstracting boilerplate (e.g., event stores, projections).
• Laravel Synergy: Deep integration with Laravel’s ecosystem (Eloquent, Livewire, Queues) reduces friction. Supports snapshots, metadata, and custom factories, making it adaptable to complex domains (e.g., financial systems, workflows).
• Alternatives Comparison:
  • Pros over raw CQRS: Built-in state management, replay safety, and Livewire hooks (e.g., commitBeforeRender).
  • Cons vs. Spatie/EventSauce: Less mature (no dependents), but more opinionated (e.g., forces "verbs" over traditional events).

Integration Feasibility

• Database: Supports MySQL/PostgreSQL (via JSON serialization). Requires verb_events and verb_snapshots tables (migrations provided).
• Dependencies:
  • Core: PHP 8.1+, Laravel 10–13.
  • Optional: bits (for IDs), livewire (for real-time commits).
  • Conflicts: None critical; avoids coupling with ORM (e.g., Eloquent optional).
• Testing: Includes event store testing utilities and wormhole time travel for replay scenarios.

Technical Risk

• Immutability: Events are immutable, but state mutations must be explicit (risk of unintended side effects if not modeled carefully).
• Performance:
  • Snapshots: Reduce replay time but increase storage.
  • Concurrency: Uses optimistic locking (via last_event_id); conflicts require retry logic.
• Debugging: Event lifecycles (e.g., boot, apply, fire) can be opaque. Logging middleware recommended.
• Migration Path:
  • Greenfield: Ideal for new projects.
  • Brownfield: Requires strategic refactoring (e.g., wrap existing models in State classes).

Key Questions

1. Domain Suitability:
   • Is the use case event-centric (e.g., order processing, user activity) or CRUD-heavy?
   • Will snapshots be needed for performance, or is pure event sourcing acceptable?
2. Team Readiness:
   • Comfort with event-driven design? Verbs abstracts complexity but requires mindset shift.
   • Experience with Laravel testing (e.g., Wormhole for time manipulation).
3. Operational Trade-offs:
   • Acceptable storage overhead for snapshots?
   • Tolerance for replay delays during high concurrency?
4. Long-Term Viability:
   • Will the package’s active development (last release: 2026) align with project timelines?
   • Preference for vendor lock-in vs. custom solutions?

Integration Approach

Stack Fit

• Laravel Core: Seamless integration with Eloquent, Queues, and Livewire.
  • Example: Use verb() helper in Livewire components to commit events before render.
• Database:
  • MySQL/PostgreSQL: JSON-based storage (no schema migrations for events).
  • Alternatives: Custom event stores possible via EventStore interface.
• Testing:
  • Pest/PHPUnit: Built-in Wormhole for time travel and EventStore mocks.
  • Feature Tests: Simulate event replays with Verbs::replay().

Migration Path

1. Assessment Phase:
   • Audit write-heavy endpoints (e.g., orders, payments) for verb candidates.
   • Identify read models that can derive from events (vs. snapshots).
2. Pilot Phase:
   • Isolate a domain: Start with a single aggregate (e.g., Order).
   • Replace Eloquent model with State class:

     class OrderState extends State
     {
         public function place(OrderPlaced $event) { /* ... */ }
     }
     

   • Use Verbs::commit() instead of Model::save().
3. Full Adoption:
   • Replace CRUD controllers with verb-based handlers.
   • Migrate queries to projections or snapshot-based reads.
   • Phase out traditional created_at/updated_at in favor of event timestamps.

Compatibility

• Laravel Versions: Officially supports 10–13; test for 9.x if needed.
• Third-Party:
  • Livewire: Native support for real-time commits.
  • Queues: Events can be dispatched asynchronously.
  • Octane: Test for long-running process bugs (fixed in v0.4.5+).
• Legacy Code:
  • Hybrid Approach: Use Verbs::fire() alongside existing event emitters.
  • Adapters: Wrap Eloquent models in State classes incrementally.

Sequencing

1. Setup:
   • Install: composer require hirethunk/verbs.
   • Publish config: php artisan vendor:publish --tag=verbs-config.
   • Run migrations: php artisan migrate.
2. Development:
   • Generate states: php artisan verbs:state Order.
   • Define verbs in State classes (e.g., place(), cancel()).
3. Testing:
   • Write replay tests using Wormhole.
   • Test snapshot consistency with Verbs::snapshot().
4. Deployment:
   • Monitor event store growth (size/performance).
   • Implement circuit breakers for replay failures.

Operational Impact

Maintenance

• Boilerplate Reduction:
  • Pros: Eliminates manual event store implementations.
  • Cons: Custom logic (e.g., complex projections) may still require bespoke code.
• Dependency Updates:
  • Monitor bits (for IDs) and Laravel version compatibility.
  • Critical Path: Event serialization/deserialization (e.g., json_encode pitfalls).
• Debugging:
  • Tools: Use Verbs::debug() to inspect event lifecycles.
  • Logs: Enable verb.* logging channel for replay issues.

Support

• Learning Curve:
  • Team Onboarding: 2–4 weeks for developers unfamiliar with event sourcing.
  • Resources: Docs are comprehensive but assume Laravel familiarity.
• Community:
  • GitHub: Active issues/PRs (515 stars, MIT license).
  • Slack/Discord: Community support via Laravel Discord.
• SLAs:
  • Replay Failures: Define SLOs for event processing (e.g., 99.9% success rate).
  • Snapshot Corruption: Backup strategy for verb_snapshots.

Scaling

• Performance:
  • Event Store: Index occurred_at for time-range queries.
  • Snapshots: Use read replicas for projection queries.
  • Concurrency: Optimistic locking (last_event_id) may require retries under high load.
• Storage:
  • Event Retention: Implement TTL policies for old events.
  • Snapshot Frequency: Balance between replay speed and storage (e.g., snapshot every 10 events).
• Horizontal Scaling:
  • Stateless Workers: Events can be processed by multiple queue workers.
  • Database: Ensure verb_events table is sharded if using multi-tenant setups.

Failure Modes

Ramp-Up

• Onboarding Checklist:
  1. Architecture Decision Record (ADR): Document why event sourcing was chosen.
  2. Workshop: Hands-on session with the Verbs Workbench.
  3. Pilot Project: Start with a non-critical domain (e.g., notifications).
• Training:
  • Concepts: Event lifecycles (boot, apply, fire), state vs. events