Download the PHP package ramir1/laravel-planner without Composer

Laravel Planner

Database-backed planner of one-off deferred artisan commands for Laravel.

Laravel has queues (including delayed jobs) and a scheduler for recurring commands. A delayed job, however, lives inside the queue backend: you cannot list it, cancel it, or survive a queue flush. Planner stores every planned run in a table: schedule a command for a given moment, group runs, cancel them and see what happened to each one.

Русская версия

Installation

planner:run is registered in the Laravel scheduler automatically (every minute, without overlapping), so make sure the scheduler (schedule:run / schedule:work) and a queue worker are running.

By default (PLANNER_SCHEDULE=inline) the planner runs inside the already booted schedule:run process: no extra PHP process is started every minute, so an empty planner costs two cheap queries. Set PLANNER_SCHEDULE=process to run it as a separate php artisan planner:run process, or false to register nothing and run planner:run yourself.

In inline mode use an asynchronous queue: with QUEUE_CONNECTION=sync the planned commands are executed right inside schedule:run and delay the other scheduled events.

Publish the config if you need to change defaults:

Writing a command

Any artisan command can be planned; the command knows nothing about the planner. Pass models by id. Business decisions ("not relevant any more", "cancel the remaining runs") belong to the command:

The planner only runs the command and records the result: exit code 0 — done; any other code or an exception — retried after backoff seconds, failed after max_attempts. The command output is stored in the task message (up to 1000 characters).

Scheduling

From the console — time is anything Carbon::parse() understands, in the application timezone:

From code:

schedule() does not check that the command exists (that would load every command of the application on each call); an unknown command fails when it runs. planner:at does check it.

source (optional morph, source: $orderLine) records where a run came from, e.g. a paid order line.

Statuses and execution

pending → running → done | failed; canceled — cancelled before it ran (cancelGroup()).

Every minute planner:run takes due pending runs (oldest run_at first, up to batch), atomically marks each one running and dispatches RunPlannedTaskJob to the queue. The worker runs the command in-process via Artisan::call() — no new PHP process, so the overhead per run is negligible compared to the command itself (about 0.1 ms for an empty command). Runs are dispatched in run_at order but executed in parallel by the workers; a group is for cancelling together, not for ordering.

A run stuck in running longer than stuck_after minutes (dead worker) is returned to pending; a stale job of such a run is ignored, so it is not executed twice.

Missed runs

A run is due when it is pending and run_at <= now(); this is checked once a minute, so a run starts within about a minute after run_at (plus the queue wait). Runs live in the database, so nothing is lost while the server is down: after it comes back, the first planner:run dispatches every missed run (oldest first, up to batch per minute).

There is no "too late" limit — a run late by a week still executes. If a late run makes no sense, the command checks it itself:

A run interrupted by a shutdown stays running and is returned to pending after stuck_after minutes, then executed again — write commands so that a repeated run is safe.

run_at is stored in the application timezone (app.timezone); changing it shifts all planned runs.

Configuration

Testing

License

MIT