Virtual Cron

categoryHow To edit_calendar31 Mar 2026

Using Virtual Cron

GeniXCMS v2.0.0 introduces the Cron class, allowing modules and themes to schedule recurring or one-time tasks without needing a system-level crontab.

GeniXCMS's cron is "virtual"—it checks for due tasks on every visitor's request.

🚀 Basic Usage

To use the Cron system, you typically:

Attach a function to a custom hook.
Schedule that hook using the Cron class.

🐘 1. Attach a Hook

Your module or theme should define what happens when the cron runs:

// in inc/mod/my_module/function.php
Hooks::attach('my_daily_sync', function($args) {
    // Perform sync logic here...
    // $args will be an array of arguments passed during scheduling
});

🗓️ 2. Schedule the Task

It is best to schedule the task once when the system starts up or during module activation:

// Schedule a daily task
if (!Cron::getNext('my_daily_sync')) { // Check if already scheduled
    Cron::schedule(time(), 'daily', 'my_daily_sync', ['force' => true]);
}

🔍 Checking Scheduled Tasks

You can check when the next run for a specific hook is scheduled:

$next_run = Cron::getNext('my_daily_sync');
if ($next_run) {
    echo "Next run: " . date('Y-m-d H:i:s', $next_run);
}

🗑️ Clearing Schedules

If you no longer need a scheduled task (e.g., when a module is deactivated), you should clear it:

Cron::clear('my_daily_sync');

🔧 One-Time Events

To run a task exactly once in the future:

// Run 30 minutes from now
Cron::scheduleOnce(time() + 1800, 'send_follow_up_email', ['user_id' => 45]);

➕ Adding Custom Intervals

By default, hourly, twicedaily, daily, and weekly are available. You can add more using the cron_schedules filter:

Hooks::attach('cron_schedules', function($schedules) {
    $schedules['every_five_mins'] = [
        'interval' => 300,
        'display'  => _('Every 5 Minutes')
    ];
    return $schedules;
});

⚙️ Triggering via Real System Cron (Better Performance)

While virtual cron works on every request, it can cause slight delays for visitors or might not run at all if there is no traffic.

For high-traffic or mission-critical sites, you can trigger the cron via a real crontab on your server:

## Add to your system crontab (e.g. crontab -e)
* * * * * curl https://your-site.com/index.php > /dev/null 2>&1

Or you can create a dedicated PHP script that only runs Cron::run().