The "runcronjobs.php" script located in the root of the eZ Publish directory takes care of processing your cronjobs in the background. This script should be executed periodically. The most common practice is to instruct the operating system (or some application) to automatically run the script at regular intervals. On UNIX/Linux systems, this can be done by making use of "cron". On Windows, the script can be run by the "Scheduled Tasks" service. The following text describe how this script can be executed.

Running cronjobs from the shell

It is possible to execute the "runcronjobs.php" script manually from within a system shell:

1.  Navigate into the eZ Publish directory.

2.  Run the script (replace "example" with the actual name of the siteaccess):

   php runcronjobs.php -s example group_of_tasks
   

 The "group_of_tasks" option indicates that only scripts listed in the "[CronjobPart-group_of_tasks]" section of the "cronjob.ini" configuration file (or its override) will be executed. This parameter is optional. If omitted, the list of scripts will be taken from the "[CronjobSettings]" section of the "cronjob.ini" configuration file. (Please refer to the "Configuring cronjobs" section for more information.)

The "-s example" indicates which siteaccess configuration the script should use. If you do not specify a siteaccess when running the script, then the default siteaccess will be used.

Debugging

It is also possible to use the "-d" parameter that instructs the script to display the debug output at the end of execution, e.g.:

php runcronjobs.php -d -s example group_of_tasks

You can use this parameter with the "all" option to get more detailed information:

php runcronjobs.php -dall -s example group_of_tasks

The following options are also available: "accumulator", "debug", "error", "include", "notice", "timing", "warning". Please note when provided, they must be separated using commas. The instructions given in the following example will tell the script to display debug notices and produce a list of includes:

php runcronjobs.php -dinclude,notice -s example group_of_tasks

The script will not make any changes to log files by default (the ones located in the "var/log" directory of your eZ Publish installation). If you need this functionality, you'll have to run the script using both "-d" and "--logfiles" parameters:

php runcronjobs.php -d -s example --logfiles group_of_tasks

It can also be displayed debug output including the SQL queries executed, by using the "--sql" parameter as shown in the following example:

php runcronjobs.php -d --sql -s example group_of_tasks

Please note that the "--sql" parameter still depends on "-d" and both need to be used simultaneously in order to have SQL debug output. Without the use of the "-d" parameter no output will be displayed at all.

Cronjobs on UNIX/Linux

"Cron" is the name of a utility that allows the automatic execution of tasks in the background. It is typically used for periodic system administration and maintenance tasks (for example, creating a weekly backup). A program often referred to as the "cron daemon" is running silently in the background, spending its time waiting and executing cronjobs. A "cronjob" is a script or a command that is run at specified intervals by the daemon. The cronjobs must be set up in a crontab. A crontab is a text file that contains information about the intervals and the tasks that should be executed. The crontab files are not intended to be edited directly. The following table reveals which shell commands that can be used for maintaining crontabs:

crontab /var/www/ezpublish/ezpublish.cron

crontab -l

crontab -e

crontab -r

The following example shows how a cronjob for eZ Publish can be set up in the crontab. It assumes that eZ Publish is located in "/var/www/ezpublish/", that the PHP command line interface program is located at "/usr/local/bin/php" and that the name of the target siteaccess is "example".

# The path to the eZ Publish directory.
EZPUBLISH=/var/www/ezpublish
 
# Location of the PHP command line interface binary.
PHPCLI=/usr/local/bin/php
 
# Instruct cron to run the main set of cronjobs
# at 6:35am every day
35 6 * * * cd $EZPUBLISH && $PHPCLI runcronjobs.php -q -s example 2>&1
 
# Instruct cron to run the "infrequent" set of cronjobs
# at 5:20am every Monday
20 5 * * 1 cd $EZPUBLISH && $PHPCLI runcronjobs.php infrequent -q -s example 2>&1
 
# Instruct cron to run the "frequent" set of cronjobs
# every 15 minutes
0,15,30,45 * * * * cd $EZPUBLISH && $PHPCLI runcronjobs.php frequent -q -s example 2>&1
 
# Instruct cron to run the "monthly" set of cronjobs
# at 4:10am the first day of every month
10 4 1 * * cd $EZPUBLISH && $PHPCLI runcronjobs.php monthly -q -s example 2>&1

When added to the crontab, the cron daemon will run the "runcronjobs.php" script using the PHP command line interface binary at the specified time. With this configuration, the main set of cronjobs will be run at 6:35am every day. This means that all the scripts listed in the "[CronjobSettings]" section of the "cronjob.ini" configuration file (or its override) will be executed once a day.

The "infrequent" set of cronjobs will be run at 5:20am every Monday, i.e. the scripts listed in the "[CronjobPart-infrequent]" section of "cronjob.ini" (or its override) will be executed once a week.

The "frequent" set of cronjobs will be run every 15 minutes. Only the scripts that are listed in the "[CronjobPart-frequent]" section of "cronjob.ini" (or its override) will be executed.

The "monthly" set of cronjobs will be run at 4:10am the first day of every month, i.e. the script(s) listed in the "[CronjobPart-monthly]" section of "cronjob.ini" (or its override) will be executed once a week.

The "-q" parameter instructs the script to run in quiet/silent mode (suppressing unnecessary output). The "-s example" indicates which siteaccess configuration the script should use. The "2>&1" notation instructs the system to combine standard output and error messages into one stream.

Scheduled tasks on Windows

Unlike UNIX/Linux systems, Windows does not provide access to cron. Instead, Windows has its own solution called "Scheduled Tasks". A scheduled task can be set up by selecting "Scheduled Tasks" from the Control Panel. This will bring up a wizard that asks what should be executed, when and so on. It should be configured to run a batch (.bat) file at regular intervals. The batch file should navigate into the eZ Publish directory and run the "runcronjobs.php" script.