Cron

Cron is used to periodically execute some job. Every module can define several methods with different intervals.

All you need to do is to set up a system to run cron.php file at least as frequently as the shortest interval defined by modules that use cron.

EPESI will manage cron tasks period. In other words - if you've got a task every 10 minutes, then it's ok to set up cron for 1 minute interval. Your task will not be executed more than once per 10 minutes. All other 9 calls to cron.php will do nothing.

Because of that you should set cron as frequently as you can. 1 minute interval is suggested.

IMPORTANT

With 1.6.0 and 1.6.1 versions you have to set up cron to make upper-right corner search working. Since 1.6.2 search will work without cron, but it's recommended to use cron.

Modules That Use Cron

Utils/RecordBrowser - search engine index

Utils/Messenger - send emails with alerts

Premium/CampaignManager - send campaign emails

Premium/Warehouse - some synchronization tasks

Premium/GeneralContractor/Planner

Until 1.6.0 version only one of the core modules required cron - Utils/Messenger. It has been working without cron, but not sending emails.

Since 1.6.0 Utils/RecordBrowser requires cron to create search index. Since 1.6.2 Utils/RecordBrowser recommends cron to create search index, but it will be also created by browser AJAX requests.

How to Configure - File Execution

Note: all examples are based on linux operating system. You have to adjust them for your server's operating system.

You have to periodically execute cron.php file, that's located in the main folder of EPESI. It depends on your server (or hosting) how to set up cron job.

Execution of cron.php file means run it through PHP interpreter.

You have to remember about running it as a proper user - as it would be ran by http server.

$ sudo -u <HTTP Server user> php <EPESI_DIR>/cron.php

For example - apache as a user and /var/www/epesi as EPESI_DIR:

$ sudo -u apache php /var/www/epesi/cron.php

If you'd like to store log for the job, then you can redirect stdout and stderr to the log file

Where: username is your cPanel username and _epesidirectory is public_html or a subdirectory of public_html as in the example above.

This is how the cron admin screen should look like. Please note Last Run date and time:

In some cases you'll have to set up cron in the /etc/cron.d/ folder. It's recommended to create a separate file with desired name and put there:

* * * * * apache php /var/www/epesi/cron.php

Please review your cron settings help, because user argument is optional and some cron servers does not allow to set it.

How to Configure - URL Fetch

Many hosting providers allow to set cron in the way, where some server job loads specific url in defined time periods. You have to obtain EPESI specific url from Menu -> Administrator -> Cron. This url contains unique token, that's also saved on disk. Cron tasks will be executed only if a valid token is supplied. This prevents from unwanted requests to cron.php file.

This method of running cron has some drawbacks. Your cron call may be terminated because of query time limits. It depends on server configuration.

If your hosting provider allows you to set by url, or by file execution, always use the latter one. Please refer chapter above for more information about file execution.

How EPESI Cron Works

This is a detailed description made for people who'd like to know behind the scenes.

System runs cron.php file through commandline or url fetch

Token validation for url fetch method - prevent DoS attacks

Check for token $_GET variable

If it's supplied, then check for file DATA_DIR/cron_token.php

Compare stored and supplied tokens

Check for lock file to prevent multiple execution of the same function

Finish if DATA_DIR/cron.lock exists

Create lock file otherwise

Load EPESI, set time limit to unlimited, increase memory_limit

Call all cron common methods to retrieve all possible cron jobs

List all methods that has to be executed - all methods, that hasn't been ran for specified interval time and are not currently executed

Pick the oldest job

Remove cron.lock file - allows to pick next job in the next cron.php execution, even when the previous job is still running

Mark selected job as running in the database

Run method! (Note that only one method is running every cron.php file call)

Log errors or output to DATA_DIR/cron.txt file.

Mark selected job as not running

With this approach we can execute all cron jobs and do not starve any. But as you can see you have to execute cron.php as often as it's possible. EPESI will handle rest - it won't execute any job more often than it should.

Here's description by example. We've got three cron jobs to execute. A (1 minutes), B (1 minutes) and C (3 minutes). We've set to run cron.php every one minute.

Things get even more complicated, when some job is time consuming. If it'll last more than it's interval, then it will be executed only if previous execution has finished.

Use Cron in Your Module

To use cron in your module you have to implement cron() method in Common file. This method has to return array of functions to execute in format function name => interval in minutes. Function has to be static method in the same class (Common).

Any return or printed text will be treated as error message. If your cron job has been executed without issues you must not return value or print any text.