Cron & CLI scripts

TubePress runs its recurring work — recalculating rankings, polling transcode jobs, importing feeds, refreshing sitemaps and more — without requiring you to configure a system crontab. This page explains the pseudo-cron, the heartbeat that keeps it alive, and the optional command-line scripts for advanced hosts.

The pseudo-cron

The CronManager is a WordPress-style scheduler. Tasks are registered with a name and an interval, and CronManager::run() is called once at the end of every page render. Each task only runs if enough time has passed since it last ran.

// Register a task (typically from a plugin's boot() method)
CronManager::register('promo_refresh', 600, function () {
    Promo::rebuildCache();   // runs at most every 10 minutes
});

It is engineered to be safe on any host:

• Atomic locking. A conditional UPDATE on the settings table claims each run, so two simultaneous requests can never run the same task twice.
• Persistent timestamps. Last-run times are stored in settings (with autoload = 0), so the schedule survives restarts and crashes — the next page load simply picks up where it left off.
• Automatic backoff. A task that keeps throwing is retried with an exponentially growing interval (capped at one hour) until it recovers, and the failure counter resets on success.

The heartbeat — no crontab required

A pseudo-cron only fires when pages are being rendered, which is a problem for a brand-new or low-traffic site. TubePress solves this with a self-managed heartbeat: a lightweight CLI process (bin/heartbeat.php) that pings your home page roughly every 50 seconds so the scheduler keeps ticking even with zero visitors.

• It is PID-guarded and re-spawned automatically by any web request if it ever dies — you do not start or supervise it.
• Turn it off at runtime by setting heartbeat_enabled to 0.

What runs on the scheduler

The core and the bundled plugins register their own tasks — for example CTR score recalculation, transcode job dispatch and retry, feed imports, catalogue processing, AI translation jobs and sitemap refreshes. As you enable subsystems they add their tasks automatically; there is nothing to wire up.

Optional CLI scripts

For heavy or one-off operations, a few command-line scripts ship in bin/ and can be run manually or from a real crontab on capable hosts. They include long-running workers (for catalogue downloads and bulk deletions) and maintenance helpers. Run them with the system PHP CLI from the project root:

php bin/heartbeat.php        # run the heartbeat in the foreground
php bin/catalogue-worker.php # process catalogue download jobs

Using a real crontab (advanced)

If you prefer to drive the scheduler from the operating system — for instance on a high-traffic site where you want tight, predictable timing — you can disable the heartbeat and add a single system cron entry that requests your home page (or runs the heartbeat once) on a short interval. Most operators never need this; the built-in heartbeat is enough.

Next steps