Event Queue Laravel Package

Getting Started

1. Install and let Laravel discover the service provider:

   composer require micro-module/event-queue
   

2. Publish the config and migrations (check the README for exact tags — this package ships both):

   php artisan vendor:publish --provider="MicroModule\EventQueue\EventQueueServiceProvider"
   php artisan migrate
   

3. Open config/event-queue.php first. That file is the real documentation: it tells you the storage table, the queue connection/name to use, retry counts, and whether processing is driven by Laravel's queue worker or a package-specific command.
4. Verify the worker path. Either the package registers its own job/command (e.g. php artisan event-queue:work) or it pushes standard Laravel jobs — run php artisan list | grep -i event and inspect routes//src/Console if the README is thin.
5. First use case: move a slow listener off the request cycle. Instead of a synchronous listener that writes audit rows, sends mail, or calls a third-party API, record the event through the package and let a worker pick it up. A good smoke test is a single UserRegistered event that writes a row to the package table and is later processed by the worker — confirm the row transitions from pending to processed before wiring in real business logic.

Implementation Patterns

Transactional outbox for domain events. The strongest day-to-day use of a DB-backed event queue is writing the event record in the same transaction as the business change, then processing asynchronously. That guarantees you never emit an event for a rolled-back write:

DB::transaction(function () use ($order) {
    $order->update(['status' => 'paid']);
    EventQueue::push(new OrderPaid($order->id)); // or the package's dispatch helper
});

Keep listeners idempotent (key on the event's stored ID or a natural key) because at-least-once delivery is the norm.

Payload discipline. Store scalars, not Eloquent models. Pass $order->id and re-fetch inside the handler. If the package uses SerializesModels, models still get re-queried and can be deleted mid-flight — IDs make that failure obvious instead of silent.

Handler/hook registration. Most micro-module packages let you map event classes to handlers in config or via a handle method. Register handlers in a dedicated service provider and keep them thin: resolve a domain service, call it, return. Avoid DB writes in the handler that duplicate the outbox row.

Ordering per aggregate. If you need per-order or per-user ordering, route events to a queue name derived from the aggregate key (e.g. orders-{shard}) or process with a single worker where ordering matters. Don't assume global ordering across workers.

Retries and dead-lettering. Point the package's queue at a dedicated connection (event-queue connection with its own Redis/DB queue) so event work doesn't starve user-facing jobs. Set tries/backoff in the config, and monitor the package's status column or failed-jobs table — whichever it exposes — rather than relying on queue:failed alone.

Integration with Laravel events. If you already dispatch Laravel events, prefer adding ShouldQueue to the event and using $event->afterCommit() for the simple cases; reserve this package for when you need persistence, replay, or an audit trail of what was emitted. Don't route the same event through both mechanisms.

Gotchas and Tips

• Double-queueing. Adding ShouldQueue to an event and pushing it through the package will process it twice. Pick one path per event class and document it in the event's docblock.
• Transaction visibility. If the package dispatches immediately, the worker can read the event before your transaction commits and find stale data. Look for an afterCommit/dispatchAfterCommit option; if it doesn't exist, push after the transaction closes.
• Config caching. php artisan config:cache in deploy will freeze the table/queue names. Run config:clear before config:cache in your deploy script, and restart workers after every deploy (queue:restart).
• Migration collisions. With zero stars and no dependents, the migration is unlikely to be battle-tested against custom schemas. Read the published migration before running it in production; consider renaming the table via config rather than editing the migration.
• Serialization failures don't surface until the worker runs. Add a test that pushes a representative event and runs the worker once in the test suite. Queue::fake() won't cover a package-managed table — assert on the DB row instead.
• Idempotency is your job. Duplicates happen on worker crashes and retries. Use updateOrCreate, unique constraints, or a processed-event ledger keyed by the stored event ID.
• Low-maintenance risk. Pin an exact version in composer.json, and treat the package's src/ as the source of truth once installed. If you need behaviour the config can't express, the usual extension points are a custom event model (subclass the package's model and rebind it in a service provider), a custom handler resolver, or wrapping the dispatcher in your own service so you can swap the package later without touching call sites.
• Observability. Count pending rows and oldest-pending age in a dashboard query — that single metric catches a stopped worker faster than log grepping.