Weave Code
Laravel Long Running Tasks Laravel Package
spatie/laravel-long-running-tasks
Monitor externally executed long-running tasks in Laravel by polling instead of webhooks. Extend LongRunningTask, implement check() returning TaskResult::ContinueChecking or StopChecking, and start with MyTask::make()->meta($data)->start(). Checks run on a configurable interval until the task...
Spatie's Laravel Long Running Tasks package helps you monitor external, long-running tasks that require polling instead of webhooks—such as AWS Rekognition jobs. You define a task by extending LongRunningTask and implementing a check() method that returns TaskResult::StopChecking or TaskResult::ContinueChecking, letting the package re-run the check on a configurable interval (10 seconds by default).
Start a task with MyTask::make()->meta($data)->start() and the package handles repeated polling until completion.
- Simple task class with a single
check()method - Configurable check frequency via config
- Pass arbitrary metadata through
meta() - Results control whether polling continues or stops
- Migrations included for task log storage
Frequently asked questions about Laravel Long Running Tasks
- How do I install spatie/laravel-long-running-tasks in a Laravel app?
- Install it with composer require spatie/laravel-long-running-tasks, then publish and run the package migrations and publish the config file, typically via php artisan vendor:publish followed by php artisan migrate. No external SaaS or additional infrastructure is introduced beyond the database and queue your app already runs. After that, create a class that extends LongRunningTask and implement its check method.
- How often does the package run check() and how do I change the polling interval?
- When check() returns TaskResult::ContinueChecking, the package re-dispatches the check call on a configurable interval, 10 seconds by default through default_check_frequency_in_seconds in the config file. Returning TaskResult::StopChecking ends the task so no further checks are scheduled. Frequency can be layered globally in config, as a property on the task class, or per instance using fluent calls.
- Which Laravel and PHP versions does this package support?
- The package targets modern Laravel applications, with the evaluation citing Laravel 10 through 12 on PHP 8.1 and above, backed by a Redis, SQS, or database queue. Always confirm the exact PHP, Laravel, and database constraints in composer.json before adding it to a platform. Because it is a small, low-usage package, also check its upgrade cadence against your own support policy.
- How do I pass data or context to a long-running task?
- Call meta() with an array before start(), for example MyTask::make()->meta($data)->start(), then read it back inside check() through $logItem->meta. The README shows scraping values out of meta in a model creating hook to fill custom columns; that works but couples your caller to the model schema. Prefer storing a stable identifier plus exactly what the check needs to call the external service.
- What does TaskResult::StopChecking do and how do I end a task?
- TaskResult is a two-case enum: ContinueChecking keeps polling on the configured interval, while StopChecking marks the task finished and stops further checks. The package only records state and re-dispatches the check job; the real work happens on the external service. Use StopChecking on completion and consider stopping explicitly on unrecoverable errors instead of looping forever.
- What is the default timeout for keeping a task checked and should I change it?
- The default keep_checking_for_in_seconds is 60 * 5, so a task stops being checked after roughly five minutes, which is far too short for video rendering, model training, or similar external jobs. Tune it deliberately per task using the global config, a class property, or a per-instance fluent call. Leaving the default in place is a common way to have long jobs silently stop being polled.
- Does this package require a queue worker?
- Yes. check() runs as a queued job that the package re-dispatches, so a working queue connection and running workers are mandatory. If workers are down or backlogged, checks simply never fire; the package tracks status but does not appear to ship heartbeats or alerting. Monitor queue health and job latency as part of production setup.
- Can two workers run the same check() at the same time, and is check() idempotent?
- The README does not document how log items are claimed or locked, so it is unclear whether two workers can process the same item simultaneously. If your check() has side effects, design it to be idempotent and verify claim semantics with a spike before relying on the package. Running a few workers against a single log item is a quick way to answer this.
- How are failures handled and what observability hooks exist for monitoring tasks?
- Failure semantics are ambiguous: when check() throws, onFail can return ContinueChecking, and returning nothing ends the task, which makes silent failure modes easy to build. The README's Events section is empty, so dedicated observability hooks may be undocumented or incomplete. Wire your own logging and alerting around the task log items and queue failures.
- Is spatie/laravel-long-running-tasks production-ready, or should I build this pattern myself?
- With zero dependents, a modest star count, and an anomalous future-dated last release, treat it as a convenient standardisation of a pattern most teams hand-roll rather than a battle-tested dependency. It fits well when you already run reliable queues and integrate with services that lack webhooks, such as AWS Rekognition, transcoding, or async AI inference. If that fit is not exact, a small jobs table plus a scheduled query is a low-effort alternative with an easy exit path.
Weaver
How can I help you explore Laravel packages today?