Anvyr Docs
Documentation menu Anvyr Loom 1.x
Anvyr Loom

Version 1.x

← All documentation

GuideAnvyr Loom 1.xOperator

Schedule recurring work

Register due tasks, run the scheduler from cron, and plan for retries and overlapping runs.

On this page

Register tasks during application boot

The container registers a shared Anvyr\Loom\Scheduling\Schedule. Register tasks in an enabled module's boot() method so each CLI or HTTP bootstrap sees the same declarations. This block is the body of that method, with the imports moved to the module file header:

use Anvyr\Loom\Contracts\CacheDriver;
use Anvyr\Loom\Scheduling\Schedule;

$schedule = app(Schedule::class);
$schedule->call(static function (): void {
    app(CacheDriver::class)->set('notes.scheduler.heartbeat', 'ok', 120);
})->everyMinute();

$schedule->command('diagnose --json')->dailyAt(3, 15);

The heartbeat is a minimal verifiable callback. Replace it with application work, or dispatch a background job when the work belongs in the queue. Registering a task does not execute it.

Run the dispatcher every minute

From the application's root:

php loom schedule:run

The command finds tasks due at the current time and executes them in sequence, in the foreground. It exits after the current pass; it is not a daemon. Arrange an external trigger, for example a crontab entry using the actual paths on your host:

* * * * * cd /srv/notes && /usr/bin/php loom schedule:run >> /srv/notes/storage/logs/scheduler.log 2>&1

Use an absolute PHP binary, a working directory, and an environment appropriate to the application. Ensure the log directory is writable. Test that the registered task appears and runs under the same process environment as cron, not only your interactive shell.

Available frequencies

Method Due time
everyMinute() Every minute
hourly() Minute zero of every hour
daily() Midnight
dailyAt(3, 15) 03:15 each day

These are the public frequency methods in the current Task implementation. There is no public cron(), weekly(), everyFiveMinutes(), timezone(), or withoutOverlapping() API. Do not copy those methods from another scheduler's examples.

Due checks use PHP's current timezone, set from app.timezone by application boot. There is no per-task timezone or missed-run catch-up. A task scheduled at 03:15 is checked against the current minute; a later invocation does not replay it automatically.

Pass callback arguments

$schedule->call(static function (string $label): void {
    app(\Anvyr\Loom\Contracts\CacheDriver::class)->set('notes.scheduler.label', $label, 120);
}, ['daily-report'])->everyMinute();

The callback receives its declared parameter array. Command tasks behave differently: put CLI arguments directly in the command string, as in command('diagnose --json'). Although command() accepts a parameter array, the current execution path does not append that array to the spawned command.

Account for overlap and failure

Two external invocations can execute the same due task twice in the same minute. There is no built-in lock, deduplication, persistent execution history, or automatic retry. Use idempotent work and a host/service-level lock if overlapping runs would be harmful. A long foreground task delays the tasks after it.

A callback exception stops the current dispatch pass. A command is spawned with passthru(); the runner does not turn the child's exit status into a reliable aggregate success report. Monitor actual task outcomes and logs rather than treating a zero scheduler exit status as proof that every command succeeded.

Optional HTTP trigger

The framework can register GET /system/cron when app.cron_enabled is true. Authorization requires a non-empty configured cron token; the handler also supports signed URL settings, an IP allowlist, and rate limiting. The route is disabled by default.

Use the CLI trigger when available. If your deployment needs the HTTP route, configure its authentication and exposure deliberately and inspect WebCronController. A URL token can appear in access logs; do not publish real trigger URLs in documentation or monitoring output.

Verified against Schedule, Task, and ScheduleRunCommand. The example checks execute callbacks locally and inspect command registration without launching a production cron task.

Continue readingDeploy a Loom application