Cronjobs #

This page is for developers who need to know what runs in the background of a site and how to add their own scheduled work. Several features only complete through cronjobs: approved content is published, delayed content is indexed, notifications are sent, dated content is hidden. A site without its crontab looks fine and quietly stops doing those things.

Contents #

1. Parts and scripts
2. What the shipped parts do
3. Running parts
4. Scheduling
5. The Cronjobs page
6. A cronjob of your own
7. Checks before going live

Parts and scripts #

A script is a PHP file in a cronjob directory (cronjobs/ of the installation, or of an extension named in [CronjobSettings] ExtensionDirectories[]). A part is a group of scripts that run together on one schedule, declared in cronjob.ini as [CronjobPart-<name>] Scripts[]. The scripts of [CronjobSettings] Scripts[] are the default part, shown as global (Cronjobs, section 1).

What the shipped parts do #

settings/cronjob.ini has the full list (infrequent, frequent, contentcheck, contentjobs, audit, logs, notification, mailpreferences, mailbounces, unlock, cluster_maintenance, cleanuprss, cache_cleanup), and extensions add parts of their own, such as sitemaps or newsletters. List what your installation has:

php runcronjobs.php --list --allow-root-user

Running parts #

php runcronjobs.php -s <siteaccess> frequent --allow-root-user        # one part
php runcronjobs.php -s <siteaccess> --allow-root-user                 # the default part
php runcronjobs.php -s <siteaccess> --script=workflow.php --allow-root-user   # one script
./console list cron                                                    # every part as a console command, cron:<part>

Run as the user the web server runs as, so files the cronjobs write stay readable by the site. Each script takes its own lock, so a second run of the same script waits or skips (Running cronjobs from the shell).

Scheduling #

Add one crontab line per part, from the installation root:

*/5 * * * *  cd /var/www/example && php runcronjobs.php -s site frequent >/dev/null 2>&1
*/15 * * * * cd /var/www/example && php runcronjobs.php -s site >/dev/null 2>&1
17 * * * *   cd /var/www/example && php runcronjobs.php -s site infrequent >/dev/null 2>&1

These are the default schedules the Cronjobs page proposes; set your own per part with cronjob.ini [AdminSettings] CrontabSchedule_<part> (Scheduling with the crontab). Hosting panels have their own cron screens (Cron and shell access).

The Cronjobs page #

The administration lists every part and script, shows whether the crontab schedules it, runs a part or a script with live output, keeps the recent runs and counts issues, and proposes crontab lines. Use it to try a new script before scheduling it and to find out why something did not happen overnight (Cronjobs, Cronjobs console).

A cronjob of your own #

1. Write the script in extension/exp_mysite/cronjobs/exp_feed_sync.php, with a @description tag in its doc comment (the console and the page show it).

2. Declare the directory and a part in extension/exp_mysite/settings/cronjob.ini.append.php:

   <?php /* #?ini charset="utf-8"?
   
   [CronjobSettings]
   ExtensionDirectories[]=exp_mysite
   
   [CronjobPart-exp_mysite]
   Scripts[]=exp_feed_sync.php
   */ ?>

3. Clear the INI cache, run the part by hand (php runcronjobs.php -s <siteaccess> exp_mysite), then schedule it.

Quiet mode, logging and the stop switches are in Cronjob parts and the tutorial A cronjob part by hand. Long work belongs in a cronjob or a content job, not in a page request.

Checks before going live #

• To do: The frequent part and the default part are scheduled for every public siteaccess that needs them.
• To do: Workflows with approvals, delayed indexing and notifications have been tested end to end with cron running.
• To do: Cron runs as the web server's user and its output is logged or mailed to someone who reads it.
• To do: Your own parts are scheduled and documented in the project.

Related pages #

• Cron jobs for hosts
• Cronjobs for builders
• Workflows and triggers
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.