Laravel Long Running Tasks Laravel Package

Product Decisions This Supports

• Build vs. buy for async polling orchestration. Every integration with a provider that only exposes "start job / check status" (AWS Rekognition, transcription services, video encoders, e-signature, KYC/credit checks, mailing houses, government submission APIs) needs the same plumbing: persist a task record, re-check on a schedule, back off, time out, and surface status. This package is that plumbing for ~1 day of integration instead of ~1 sprint of building it. The real decision it informs is whether to standardize on one pattern for all such integrations rather than letting each team hand-roll sleep() loops or bespoke cron jobs.
• User-facing "processing status" experiences. The long_running_task_log_items table with pending / running / completed / failed / didNotComplete is a ready-made backing store for status badges, "we'll email you when your export is ready" flows, and support-tooling lookups. That makes "show progress on long jobs" a cheap roadmap item instead of a design debate.
• SLA and cost tuning as a product lever, not an engineering accident. The three backoff strategies map directly to a product tradeoff: Default (fixed 10s) = fastest completion signal, highest provider API spend; Standard backoff (10s → 60s → 120s → 300s → 600s) = near-real-time for the first minute, cheap for the long tail; Exponential/Linear = cheapest, slowest. A PM can now make an explicit call like "exports feel instant for the 80% that finish in a minute; slow ones may take up to 10 minutes to appear" and have it be one config value.
• "Never-ending task" guardrails. keep_checking_for_in_seconds (default 5 min) is a product-set abandonment policy: after this, the task is marked didNotComplete rather than hanging forever. That's a decision about when to tell a user "this failed, try again" versus leaving them waiting — worth an explicit answer per task type.
• Failure UX. onFail() returning ContinueChecking vs. nothing lets you decide, per task class, whether a transient provider error is retried silently or surfaced as a hard failure. This is the difference between "we retried and it worked" and "the user saw an error for something that self-healed."
• Roadmap scoping for integrations. It changes estimation for any "connect to vendor X" initiative: the async half of the integration collapses to a task class with a check() body. Useful when triaging a backlog of third-party integrations for sequencing.

When to Consider This Package

Adopt when:

• The app is Laravel (10+) and already runs queue workers in production — the package is queue-dependent, and no queue means no re-checks.
• You have two or more polling-only integrations, or one that's business-critical enough to want status records and failure history. For a single trivial integration, a scheduled command is fine.
• You want auditable per-task state (run counts, attempts, last exception, timestamps) without building a table yourself.
• The completion latency tolerance is measured in seconds-to-minutes, not milliseconds.
• Your team already lives in the Spatie/Laravel idiom (publishable config, publishable migrations, extendable base model and job) — the extension points here are good, which materially lowers lock-in.
• You're comfortable with a thin wrapper: subclass the model and the job, keep your own task classes behind a small internal interface, so a future replacement is a contained change.

Look elsewhere when:

• The provider supports webhooks. Polling is a fallback, not a first choice — it costs API calls and adds latency for no benefit.
• You need a real-time UI. This gives you state, not push; you'll still need broadcasting or polling on the frontend.
• Volume is high (thousands of concurrent tasks). Each check is a queue job — you'll want to model the queue load and provider rate limits before committing.
• You need durable workflow/saga semantics — multi-step orchestration, compensation, exactly-once guarantees. This is a polling monitor, not a workflow engine; reach for a proper orchestrator.
• The task is on the critical revenue path and the dependency is unacceptable. 38 stars and 0 known dependents is the headline risk: small install base, young package, effectively one maintainer org. Fine when you can vendor it or fork it; not fine when procurement or an SRE review will ask "who else runs this?"
• The team isn't on Laravel, or the effort of standing up queues for this outweighs the polling logic itself.

How to Pitch It (Stakeholders)

For executives (30 seconds): Several of our integrations work by starting a job on a vendor's side and then repeatedly asking "is it done?" Today each of those is bespoke engineering. This MIT-licensed, free package gives us that pattern once, with a status table we can show users and support, configurable retry timing so we don't over-pay for API calls, and automatic timeouts so nothing hangs forever. It converts a repeated multi-week build into a repeated one-day build. The tradeoff is maturity: it's a small, young open-source package, so we'd pin the version, wrap it in our own thin layer, and keep it off the highest-risk paths until it earns trust.

For engineering leads: Low-ceremony dependency from a well-known Laravel vendor. Three files of substance to understand: the LongRunningTask base class with check(), the LongRunningTaskLogItem model, and RunLongRunningTaskJob. Both the model and the job are designed to be subclassed and swapped via config, so we own the schema extensions and the queue behavior. Requires an existing queue setup. Recommended adoption shape: publish config and migrations, create App\Models\LongRunningTaskLogItem, keep task classes in one namespaced directory behind our own marker interface, pin to the current minor and review on upgrade. Cost is essentially zero; the risk we're accepting is maintenance risk, which the wrapper contains.

For the operating/SRE conversation: Watch the check frequency against vendor rate limits, and pick a backoff strategy explicitly rather than accepting the 10-second default. Set keep_checking_for_in_seconds per task type to match what we're willing to tell a user "this is still working." Budget queue capacity for the re-check jobs, and alert on didNotComplete and failed counts — those are the two states that generate support tickets.