Weave Code
Event Machine Laravel Package
tarfin-labs/event-machine
Event Machine is a Laravel package for event-driven architecture, offering a clean, structured API for defining and dispatching domain events, wiring up listeners, and keeping business logic decoupled, testable, and easy to extend.
Event-driven state machines for Laravel with event sourcing, type-safe context, and full audit trail.
Frequently asked questions about Event Machine
- What is tarfin-labs/event-machine?
- It is a Laravel package for building event-driven state machines with event sourcing, type-safe context, and a full audit trail. It provides a structured API for defining and dispatching domain events, wiring listeners, and keeping business logic decoupled and testable. It also integrates with Artisan and the Laravel scheduler for timer-based machines.
- How do I install event-machine in a Laravel application?
- Install the package with Composer as tarfin-labs/event-machine. It is Laravel-native and integrates through Artisan commands and the scheduler, so no separate service is required. After installation, register your timer machines and add the required schedule entries in routes/console.php.
- Which Laravel versions does event-machine support?
- The provided package context does not list explicit Laravel version constraints, so check the composer.json file in the repository before upgrading. The 9.x line is described as backward compatible at the API level, with defaults and fluent overrides unchanged. The package depends on Laravel's Artisan commands and scheduler integration.
- How do I schedule event-machine timer machines in Laravel?
- Register timer machines using MachineTimer::register() and add the corresponding machine:process-timers entries to routes/console.php. The TPM assessment notes that missing schedule entries are now surfaced by machine:validate --all. Run that validation in an artisan context where routes/console.php is loaded to confirm every timer machine is scheduled.
- What changed in event-machine 9.21.0?
- Release 9.21.0 fixes a critical scheduler integration defect by making MachineTimer::register() shell-escape the namespaced class option, matching MachineScheduler::register(). The fix is internal and does not change the public API or defaults. It also makes missing or incorrect timer schedule registrations visible through validation.
- Why are my event-machine timers not running from the Laravel scheduler?
- From version 9.3.0 through 9.20.0, registered timer sweeps could fail silently because the namespaced class option was not shell-escaped. Upgrade to 9.21.0 and run machine:validate --all to confirm the timer machines are registered in routes/console.php. Also verify that the scheduler itself is running in your environment.
- What happens to overdue timers after upgrading to event-machine 9.21.0?
- Every overdue every timer fires once on the first sweep after upgrade, regardless of how old it is; it does not fire once per missed interval. A backlog drains at timers.batch_size, which defaults to 100 per timer per sweep. Before deploying, inventory overdue instances and decide whether they should still act or be moved out of timer state.
- How do I control how fast the event-machine timer backlog drains?
- Adjust timers.batch_size, which defaults to 100 instances per timer per sweep. For large backlogs, the TPM assessment recommends moving unsafe instances out of timer state before deployment rather than relying on batch-size tuning alone. Monitor the first sweeps to confirm the backlog drains as expected.
- Why does machine:validate --all fail my CI pipeline?
- The validator fails when timer machines are missing from routes/console.php, which is intentional because unscheduled timers would otherwise fail silently. Add the missing machine:process-timers schedule entries named by the validator. Then run php artisan machine:validate --all in CI with routes/console.php loaded.
- Does event-machine provide event sourcing and an audit trail?
- Yes, the package overview describes event-driven state machines with event sourcing, type-safe context, and a full audit trail. That makes state transitions traceable and keeps domain logic decoupled from framework code. The audit trail is useful for debugging and for verifying that timer-driven transitions behave as intended.
Weaver
How can I help you explore Laravel packages today?