joseconti/klytos-scheduled-actions

Klytos Scheduled Actions & Cron

When to Use This Skill

Use this reference when your plugin needs to run background tasks: daily cleanups, periodic API syncs, deferred processing, or any task that runs on a schedule.

Klytos has two systems:

1. Action Scheduler (primary) — Flexible, supports single and recurring actions, retry logic
2. CronManager (legacy) — Simple interval-based pseudo-cron running on admin page loads

---

Action Scheduler (Primary System)

Schedule a One-Time Action

klytos_schedule_single_action(int $timestamp, string $hook, array $args = [], string $group = ''): string

Returns the action ID.

// Run in 1 hour
$actionId = klytos_schedule_single_action(
    time() + 3600,
    'my_plugin.send_report',
    ['report_id' => 42],
    'my-plugin'
);

// Handle the action when it fires
klytos_add_action('my_plugin.send_report', function (array $args): void {
    $reportId = $args['report_id'];
    // ... send the report
    klytos_log('info', "Report {$reportId} sent");
});

Schedule a Recurring Action

klytos_schedule_recurring_action(int $timestamp, int $intervalSeconds, string $hook, array $args = [], string $group = ''): string

Minimum interval: 60 seconds.

// Run every hour starting now
$actionId = klytos_schedule_recurring_action(
    time(),
    3600,                           // Every hour
    'my_plugin.sync_data',
    [],
    'my-plugin'
);

// Run daily (86400 seconds)
$actionId = klytos_schedule_recurring_action(
    time(),
    86400,
    'my_plugin.daily_cleanup',
    [],
    'my-plugin'
);

Cancel Actions

// Cancel by ID
klytos_cancel_scheduled_action(string $actionId): bool

// Cancel ALL pending actions for a hook
klytos_unschedule_all_actions(string $hook, array $args = [], string $group = ''): int

// Cancel specific action
klytos_cancel_scheduled_action($actionId);

// Cancel all sync actions
$count = klytos_unschedule_all_actions('my_plugin.sync_data', [], 'my-plugin');

Query Scheduled Actions

// Next run timestamp (or null)
klytos_next_scheduled_action(string $hook, array $args = [], string $group = ''): ?int

// Is action scheduled?
klytos_is_scheduled_action(string $hook, array $args = [], string $group = ''): bool

// Check before scheduling (avoid duplicates)
if (!klytos_is_scheduled_action('my_plugin.sync_data')) {
    klytos_schedule_recurring_action(time(), 3600, 'my_plugin.sync_data', [], 'my-plugin');
}

// Get next run time
$next = klytos_next_scheduled_action('my_plugin.sync_data');
if ($next) {
    echo "Next sync: " . date('Y-m-d H:i:s', $next);
}

Action Data Structure

[
    'id'           => string,        // UUID
    'hook'         => string,        // Hook name to fire
    'args'         => array,         // Arguments for the hook
    'group'        => string,        // Organization group
    'status'       => string,        // 'pending', 'completed', 'failed', 'canceled'
    'type'         => string,        // 'single' or 'recurring'
    'interval'     => ?int,          // Seconds between runs (null for single)
    'scheduled_at' => string,        // ISO 8601 — when it should run
    'started_at'   => ?string,       // When execution started
    'completed_at' => ?string,       // When execution finished
    'attempts'     => int,           // Current attempt count
    'max_attempts' => int,           // Max retries (default: 3)
    'last_error'   => ?string,       // Last error message
    'created_at'   => string,        // ISO 8601
    'updated_at'   => string,        // ISO 8601
]

Execution: How Actions Run

1. Server cron (preferred): Configure your server's crontab to call cli.php scheduler:run every minute
2. Fallback pseudo-cron: On every admin page load, the Action Scheduler checks for due actions

Failed actions are retried up to max_attempts (default: 3) with exponential backoff.

---

Via MCP (AI Interface)

klytos_schedule_single_action

{
    "timestamp": 1711900800,
    "hook": "my_plugin.send_report",
    "args": {"report_id": 42},
    "group": "my-plugin"
}

klytos_schedule_recurring_action

{
    "timestamp": 1711900800,
    "interval_seconds": 86400,
    "hook": "my_plugin.daily_cleanup",
    "args": {},
    "group": "my-plugin"
}

klytos_cancel_scheduled_action

{
    "action_id": "abc123-def456"
}

klytos_list_scheduled_actions

{
    "status": "pending",
    "group": "my-plugin"
}

klytos_get_scheduler_status

Returns scheduler health: queue size, last run, next run, failed count.

---

Via Admin (Desktop Interface)

• Scheduled Actions page: admin/scheduled-actions.php
• View all scheduled actions with status, next run, group
• Cancel or retry failed actions
• View execution history

---

CronManager (Legacy Pseudo-Cron)

For simple recurring tasks. Runs on every admin page load.

Register a Cron Task

klytos_add_filter('cron.tasks', function (array $tasks): array {
    $tasks[] = [
        'id'       => 'my_plugin_daily_task',
        'callback' => function (): void {
            klytos_log('info', 'Running daily task');
            // ... task logic
        },
        'interval' => 'daily',
    ];
    return $tasks;
});

Available Intervals

| Interval | Seconds | Description | |---|---|---| | 'hourly' | 3600 | Every hour | | 'daily' | 86400 | Every 24 hours | | 'weekly' | 604800 | Every 7 days | | 'monthly' | 2592000 | Every 30 days |

Core Cron Tasks

| Task | Interval | Purpose | |---|---|---| | analytics_prune | daily | Prune analytics data older than 90 days | | audit_log_prune | daily | Prune audit logs older than 90 days | | rate_limit_cleanup | hourly | Clean expired rate limit entries |

---

When to Use Which System

| Scenario | System | Why | |---|---|---| | Run once in 1 hour | Action Scheduler | Single action with timestamp | | Run every day | Action Scheduler | Recurring with 86400 interval | | Retry on failure | Action Scheduler | Built-in retry logic | | Simple daily cleanup | CronManager | Simple, no retry needed | | Process queue of items | Action Scheduler | Each item can be its own action | | Deferred heavy processing | Action Scheduler | Runs via server cron, not on page load |

Recommendation: Use the Action Scheduler for new code. CronManager is maintained for backwards compatibility.

---

Best Practices

1. Always check before scheduling to avoid duplicate actions:

   if (!klytos_is_scheduled_action('my_plugin.sync')) {
       klytos_schedule_recurring_action(time(), 3600, 'my_plugin.sync');
   }
   

2. Use groups to organize actions by plugin:

   klytos_schedule_single_action(time() + 60, 'my_hook', [], 'my-plugin');
   

3. Clean up on deactivation:

   // plugins/my-plugin/deactivate.php
   klytos_unschedule_all_actions('my_plugin.sync', [], 'my-plugin');
   klytos_unschedule_all_actions('my_plugin.cleanup', [], 'my-plugin');
   

4. Keep actions short — long-running actions may timeout. Break large tasks into smaller actions.

5. Log results for debugging:

   klytos_add_action('my_plugin.sync', function (): void {
       $start = microtime(true);
       // ... work
       $duration = round(microtime(true) - $start, 2);
       klytos_log('info', "Sync completed in {$duration}s");
   });
   

---

Source Files

• Action Scheduler: core/action-scheduler.php
• CronManager: core/cron-manager.php
• Global functions: core/helpers-global.php (lines 574-655)
• MCP scheduler tools: core/mcp/tools/scheduler-tools.php
• Admin page: admin/scheduled-actions.php