LaceTimer (Scheduled Tasks)

In LacePHP you can schedule recurring tasks (cron-style jobs) to run automatically. Think of it as your app’s built-in “cron” manager. LaceTimer:

  • Loads a JSON schedule file or code-based definitions

  • Checks which tasks are “due” right now

  • Invokes PHP class methods or shell commands

Why Scheduled Tasks Matter

  • Automate maintenance: clear caches, rotate logs, prune old data

  • Run reports: email weekly summaries, generate analytics overnight

  • Keep controllers lean: background jobs run outside of web requests

Configuration: schedule.json

By default LaceTimer looks in the aglet/ folder (sibling to weave/ and lacebox/) for a file named schedule.json. Create or rename it like this:

[
  {
    "name":    "Clear Cache",
    "cron":    "0 3 * * *",
    "handler": "php lace clear:cache"
  },
  {
    "name":    "Weekly Report",
    "cron":    "0 6 * * 1",
    "handler": "Weave\\Tasks\\ReportSender@sendDaily"
  }
]

Each entry must include:

  • name: human-readable identifier

  • cron: standard five-field cron expression (minute hour day month weekday)

  • handler: either - a shell command string (e.g. “php lace clear:cache”) - a class@method pair (e.g. “Weave\Tasks\ReportSender@sendDaily”)

Loading Code-Based Tasks

You can also register tasks in PHP code. Open aglet/kernel.php and call the global schedule() helper:

<?php
use Lacebox\Sole\Cobble\LaceTimer;

schedule()->add('Heartbeat', '*/5 * * * *', function() {
    // your code runs every 5 minutes
    error_log('Heartbeat at ' . date('c'));
});

These “code tasks” are merged with the JSON file tasks automatically.

Inspecting Your Schedule

Use the CLI to list all defined tasks:

php lace timer list

You’ll see output like:

Scheduled tasks:
 Clear Cache          0 3 * * *    php lace clear:cache
 Weekly Report        0 6 * * 1    Weave\\Tasks\\ReportSender@sendDaily
 Heartbeat            */5 * * * *  Closure

Running Due Tasks

To execute all tasks that match the current time, run:

php lace timer run

LaceTimer will:

  1. Load your JSON and code-based schedules

  2. Evaluate each cron expression against the current timestamp

  3. Invoke shell commands or PHP handlers in turn

  4. Print status messages (“Running ‘Clear Cache’…”)

You can then add to your server’s crontab:

* * * * * cd /path/to/your/app && php lace timer run >> /var/log/lace-timer.log 2>&1

And LaceTimer will only execute the tasks whose cron expressions match the current minute, skipping everything else.

Under the Hood

LaceTimer’s key methods:

  • loadSchedule() Reads aglet/schedule.json and includes aglet/kernel.php if present.

  • dueTasks() Filters tasks whose cron expression matches “now.”

  • runDue() Executes each due task and reports success or failure.

Best Practices

  • Use descriptive names for your tasks so it’s clear what each does.

  • Test your cron expressions with an online validator to avoid mistakes.

  • Delegate heavy work to queued jobs or external scripts if tasks take a long time.

  • Avoid overlap: if a task takes longer than its interval, consider locking or extending the interval.

Warning

  • LaceTimer does not daemonise; you must run php lace timer run via your system cron or supervisor every minute.

  • Ensure your PHP CLI environment matches your web environment (same .env, timezone, permissions).

  • Handle errors gracefully: shell commands should return a non-zero exit code on failure so LaceTimer can report it.

By using LaceTimer, you can automate routine jobs easily—no external cron setup required beyond a simple scheduler entry.