Kaveh Laravel Package

Getting Started

• Install with composer require <vendor>/<package> — v0.2.5 removes the bogus illuminate/foundation constraint, so if you previously had to pin an older version or add a replace/alias hack to get composer install to resolve, drop that workaround and run composer update <vendor>/<package>.
• Publish the config (php artisan vendor:publish --tag=...) and set the endpoint + credentials in .env. The two values you will actually tune first are the transport timeouts (connect_timeout: 1.0, request_timeout: 3.0 by default) and the buffer flush threshold.
• Read these three files in this order before writing any code: the config file (all knobs live there), EventBuffer (batching, flush semantics, Octane fallback), RemoteTransport (circuit breaker + timeouts). Everything surprising about this package is in those two classes.
• First use case: add a single tracking call in one controller, hit the page, and confirm the payload arrives at your endpoint. Then check the log for a flush line. If nothing arrives, you are almost certainly in the silent-drop path (see Gotchas) rather than misconfigured credentials.
• If you are on Octane, validate the package under Octane before building on it — the non-blocking fallback in EventBuffer behaves differently per SAPI and this is the single biggest behavioural fork in the package.

Implementation Patterns

Fire-and-forget from domain code. The idiomatic pattern is a thin wrapper (a Tracker service or a facade) injected into services/actions, with the package's client behind an interface. Buffer flushing is batched, so a call per domain action is cheap; a call per loop iteration is not.

Queue the flush, not the event. Because EventBuffer batches, the best throughput pattern is: record events inline (fast, in-memory), and let the buffer flush on the package's schedule or at request termination. Wrapping each individual event in a queued job throws away the batching benefit and multiplies HTTP overhead.

Explicit flush at known boundaries. For long-running processes (queue workers, artisan commands, scheduled tasks), call the flush method explicitly at the end of a batch/job rather than relying on shutdown behaviour. Non-blocking fallback means a shutdown flush is best-effort.

Laravel event/listener integration. A listener on your domain events calling the tracker is the cleanest integration and keeps tracking out of controllers. Register it in EventServiceProvider and keep the listener synchronous but trivial — do not do HTTP in the listener itself.

Testing. Use Http::fake() and assert on the outgoing request body rather than mocking the package internals. Add one test that asserts a failed request does not throw into your request lifecycle, and one that asserts events are still buffered when the transport fails — these are the two regressions that actually bite.

Graceful degradation in hot paths. Treat tracking as non-critical: wrap the call site so a transport exception cannot break checkout/login/etc. The package's own timeouts (1s connect / 3s request) already bound the damage, but the call is still synchronous before the breaker trips.

Multi-tenant / multi-connection setups. If you need different endpoints per tenant, construct separate client instances from config rather than mutating global config at runtime — the buffer and circuit breaker state are per-instance, and globally mutating config under Octane leaks between requests.

Gotchas and Tips

• The circuit breaker drops events silently. After 3 consecutive failures it trips and short-circuits for 60s. Events during that window are lost, not queued for retry. If event loss is unacceptable, add your own durable fallback (log-to-disk or a failed_events table) and reconcile later; do not assume the package retries.
• Watch for the transition into the open state. Emit a metric or log line on the first dropped event per window. Without this, a tripped breaker looks identical to "no traffic" and you will debug it for an hour.
• Timeouts are aggressive by design. connect_timeout: 1.0 / request_timeout: 3.0 protects workers, but a slow or cold endpoint will now fail where it previously (slowly) succeeded. If you have a high-latency endpoint or a proxy in front of it, raise these in config — but understand you are trading worker safety for delivery.
• Circuit breaker state and Octane. Confirm whether breaker state is per-request-resolved instance or shared across the worker. If the client is bound as a singleton, a tripped breaker persists across requests in the same worker; if it is not, the breaker never actually protects you. Check RemoteTransport's resolution in your service provider before relying on it.
• Non-blocking fallback means shutdown flushes are best-effort. Under fastcgi/FPM the buffer flushes reliably; under Octane or a CLI process the fallback may skip the final network call. Always flush explicitly in commands and jobs.
• Config caching. After upgrading, run php artisan config:clear (and config:cache in deploy). Stale cached config is the most common cause of "the new timeout settings aren't applied."
• Composer note. The illuminate/foundation removal in this release fixes installation on stock Laravel. Older lockfiles may still carry the reference — commit the updated composer.lock rather than running composer update on the server.
• Memory in long-running workers. The buffer is in-memory. Bound its size explicitly in config; an unbounded buffer in a queue worker with an unreachable endpoint is a slow memory leak.
• Extension points. The transport is the right seam for custom behaviour (signing, header injection, retry with backoff). Wrapping RemoteTransport rather than editing vendor code also lets you re-add a breaker reset hook or logging without forking.
• Debugging checklist for "events stopped arriving": 1) is the breaker open (look for 3 recent failures), 2) did config cache go stale after the upgrade, 3) is the call happening after the buffer's flush point in a non-FPM context, 4) is the request timing out at 3s against a slow endpoint. Those four cover nearly every report.