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:

.. code-block:: json

   [
     {
       "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:

.. code-block:: php

   <?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:

.. code-block:: bash

   php lace timer list

You’ll see output like:

.. code-block:: text

    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:

.. code-block:: bash

   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’…”)

.. container:: note
    
    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.

|
|