Queueing events.

Use queued tracking when writing customer health rows should happen outside the request. Inline writes remain the default because callers can observe failures immediately.

Enable queued writes

Set the package queue flag:

CUSTOMER_HEALTH_QUEUE=true

The shipped config does not read that environment variable directly. Map it in config/customer-health.php:

'queue' => (bool) env('CUSTOMER_HEALTH_QUEUE', false),
'queue_connection' => env('CUSTOMER_HEALTH_QUEUE_CONNECTION'),
'queue_name' => env('CUSTOMER_HEALTH_QUEUE_NAME'),

When queue is exactly true, CustomerHealth::track() dispatches a RecordProductEvent job and returns without writing event or milestone rows.

Null or empty connection and queue values use Laravel's defaults.

Run a worker

For a named queue:

php artisan queue:work --queue=customer-health

Match the name to customer-health.queue_name. Configure worker retries, timeouts, and process supervision through Laravel and your deployment system.

Queue payloads

The package converts the event to primitive data before dispatch:

• subject and actor morph types and IDs;
• event name, feature, and milestone flag;
• primitive properties; and
• the UTC event timestamp as a string.

The job does not serialize the subject or actor model. This avoids carrying a stale model snapshot and keeps database-per-tenant queue restoration compatible with tenant-aware queue systems.

Invalid property objects throw before the job is dispatched.

Choose the write connection

When customer-health.connection is set, the worker writes to that connection.

When it is null, the worker uses the default connection active when the job runs. It does not preserve the default connection that was active at dispatch time.

For database-per-tenant applications, configure the queue system to restore tenant context before the job handles. With Spatie Laravel Multitenancy, use a tenant-aware queue and the package's SpatieTenantResolver for landlord summary identity.

Dispatch after the business transaction

The package job implements ShouldQueue; it does not implement an after-commit queue contract. If track() runs inside an open database transaction, a worker can receive the job before the business transaction commits.

Call track() after the transaction commits or enable Laravel's after-commit behavior on the selected queue connection. This prevents the worker from recording an event for a business operation that later rolls back.

Handle retries

A retry after the first attempt committed can create a second raw event row. Milestone rows remain unique, so the retry does not create another milestone or fire MilestoneReached again.

Treat ProductEventRecorded listeners as repeatable when queued job retries are possible. If the application needs exactly-once raw events, add an application event identifier to properties and enforce deduplication in application code. The package does not provide a raw-event idempotency key.

What queued tracking does not queue

Score computation, reads, recomputation commands, pruning, and erasure remain on their calling process. The queue configuration changes only CustomerHealth::track().

What to read next

• Product events for the event data converted into the job payload.
• Production operations to supervise workers and schedule maintenance.
• Troubleshooting to diagnose missing queued events.