larger smaller normal text version of this page
Phplist Documentation » Message functions » Process the message queue »

Setting up a Cron job

What is a Cron Job

A cron job is a scheduler -commonly used in Unix-like operating systems- to periodically execute commands. These commands are read from a file, which is usually referred to as a 'crontab file'. This crontab file will be checked each minute to see if any scheduled commands need to be executed. For more info see Wikipedia: crontab

Format of a crontab file

Each line of a crontab file has a fixed scheduling format and executes one particular command. The crontab scheduling format is summarized in this scheme:

# (Use to post in the top of your crontab)
# ------------- minute (0 - 59)
# | ----------- hour (0 - 23)
# | | --------- day of month (1 - 31)
# | | | ------- month (1 - 12)
# | | | | ----- day of week (0 - 6) (Sunday=0)
# | | | | |
# * * * * * command to be executed

You can use several operators for specifying scheduling values. These are the ones commonly used:
* The comma (',') operator specifies a list of values, for example: "1,3,4,7,8"
* The dash ('-') operator specifies a range of values, for example: "1-6", which is equivalent to "1,2,3,4,5,6"
* The asterisk ('*') operator specifies all possible values for a field. For example, an asterisk in the hour time field would be equivalent to 'every hour'.
* The slash ('/') is an operator -available with some extended versions of cron support- which can be used to skip a given number of values.

Example of a crontab file:

# crontab for processing all messages with status 'queued' with PHP-cli
# - MAILQUEUE_BATCH_SIZE=0 is recommended.
# - Setting the MAILQUEUE_THROTTLE may be needed to avoid overloading the server.
# All emails will be sent in one run. Processing starts at 17 min after midnight and continues
# as long as subscribers have to be processed. This may take many hours with large lists.
# Setting up multiple entries at different hours will repeat the process queue command multiple
# times a day.
# Make sure that enough time has passed and that the previous job has finished
# before scheduling the next.
17 0 * * * /usr/bin/php /home/mydomain/public_html/lists/admin/index.php -pprocessqueue -c/home/mydomain/public_html/lists/config/config.php >/dev/null

How to setup a Cron job

Using the Unix/Linux command line
The following text is for Unix/Linux server with access to the command line (SSH access is necessary). To get additional information on managing cron jobs type 'man crontab' and to get information about the format of the crontab file type 'man 5 crontab'.

First you should check if there are still jobs running for the current user. This is done by typing 'crontab -l'. If there are, you should save them in a file at which you may append your own jobs. The command is 'crontab -l >crontab.txt'. The name of the file is free. Usually it is called crontab without any extension. Avoid placing the file in the DOCUMENT_ROOT folder branch of your web server (this is only for security). If no existing scheduled jobs are found, you can create an empty file with the command 'touch crontab.txt'.

If you use an editor on Unix, open that file for editing. If you prefer editing the file on your local computer, download the file and edit it locally. Set the scheduled times as described in 'man 5 crontab' and append on the same line the command you want to execute. At the end of the crontab file, add a new line. This avoids an end-of-file on the last schedule. Save/Upload the file. If you are working locally on Windows or Mac be aware to convert the line breaks into the Unix format. Most FTP programs can do this automatically, you just have to ensure that they are properly configured.

To load and activate your new/merged crontab.txt file you have to execute 'crontab crontab.txt' at the command line. Finally, check the result with calling again 'crontab -l'.
Note: this description is based on an excellent forum post by Jochen (jotazzu).

Using Cpanel
Some hosting providers offer the possibility to setup a cron job using the Cpanel site interface. Please consult their Cpanel tutorial or help pages for information on how to go about this. Alternatively, you should be able to find such a tutorial by searching the Internet.
See also: How to get phplist working with cpanel cron

Using your ISP
Some hosting providers do not allow users to install a cron job on the server. Instead they require you send them a copy of the crontab file you want to execute, and will then install it for you.

If you're in doubt which of the above methods you can or should use, please contact your ISP.

Useful forum threads

Page was generated in 0.0762 seconds