Grabit Bundle Laravel Package

Getting Started

• Install with composer require nicolas-joubert/grabit-bundle and, if you want the new lifecycle events, pin ^1.5.
• Publish any shipped config (php artisan vendor:publish --tag=grabit-config) and skim it first — source definitions, HTTP/transport options, and error handling defaults usually live there.
• Define your first source (the thing "GrabCo" reads from), point it at a URL or feed, and run a single manual fetch in tinker before wiring anything into a job or command. This is the fastest way to confirm credentials, transport config, and output shape.
• First real use case: put the fetch behind a queued job, persist the result, and register a listener for SourceErrorEvent so failures are visible from day one.

Implementation Patterns

• Event-driven observability (new in v1.5). Register listeners for SourceDisabledEvent and SourceErrorEvent in your EventServiceProvider (or via Event::listen in a service provider). Typical handlers: log with source context, increment a metric, notify Slack, or flip an internal sources.status column so your admin UI reflects reality.
• Job wrapping. Call the package from a queued job rather than a controller, and let the events be your failure signal instead of wrapping everything in your own try/catch. This keeps retry/backoff policy in one place.
• Scheduled sweeps. A scheduled command that iterates active sources and dispatches one job per source scales better than a single loop, and pairs naturally with the new events — a disabled source simply stops producing work.
• Persistence layer. Store raw payloads plus a normalised record; the raw copy is invaluable when a source changes its markup and you need to replay.
• Multi-tenant setups. If sources are per-tenant, scope listeners by a source attribute (tenant id) read off the event payload so notifications land in the right place.
• Testing. Fake the events (Event::fake([SourceErrorEvent::class])) and assert dispatch, rather than hitting a live endpoint.

Gotchas and Tips

• Events fire on transitions, not on every poll. SourceDisabledEvent is a state-change signal — don't build dashboards that assume one event per run. Persist the state and treat the event as an edge trigger.
• Register listeners before you rely on them. With config/route caching in production, a listener added only in a local service provider can silently not fire. Clear caches as part of deploy.
• Listeners run inside the failing path. If SourceErrorEvent fires while the source is already unhealthy, a listener that throws will obscure the original error. Keep handlers defensive and side-effect-light; push slow work (HTTP calls, mail) onto a queue.
• Don't conflate disabled with broken. SourceDisabledEvent is administrative/expected; SourceErrorEvent is a fault. Route them to different channels and different alert severities, or you'll train your team to ignore both.
• Debugging failed fetches. Log the source identifier and the underlying exception message in your listener — the event payload is your only durable record once the job has been retried and discarded.
• Upgrade note. If you're coming from 1.4.x, the events are additive, so no breaking changes expected; just bump the constraint and add listeners. Verify your event names against the class constants rather than string literals to survive future renames.
• Extension point. For behaviour beyond what the events expose, decorate the package service in a container binding rather than forking — it keeps upgrades clean.