Scheduled actions

Contents...

Among frequently arising tasks is the execution of certain actions by an application in accordance with a set up schedule without user input. An example of such an action could be regular (once every 10 minutes) checking of incoming mail.

Management of such regularly executed actions goes beyond the area of application of the Webasyst framework and shall be performed by means of special system utilities. In UNIX-like operating systems the cron daemon is used for these purposes. The Windows family operating systems also have a built-in scheduler; third-party analogs of cron are also available.

Although Webasyst does not have its own scheduler, the framework offers an infrastructure for creation of scripts, which can be launched from within the command line and, consequently, can be used to set up a cron job.

This infrastructure allows calling methods of all application classes in such scripts exactly like it is possible in a controller.

Creating a script for launching via the command line

For each action, which is supposed to be automatically executed by schedule, you need to create a separate file named according to rule wa-apps/[APP_ID]/lib/cli/[APP_ID][ACTION_NAME].cli.php

For example, wa-apps/mail/lib/cli/mailCheck.cli.php is a script, which will check new mail.

In this file it is necessary to declare a class extending waCliController. In this class the logic executed upon each request of the file must be contained in method execute():

<?php 

class mailCheckCli extends waCliController
{

    public function execute()
    {
        // write any code here, which should be executed
        // you can use models and any other application classes

        echo "Hello world!";
    }

}

Launching a script via the command line

To launch a script containing a class extending waCliController, execute a command of the following form:

php [PATH to the Webasyst root directory]/cli.php APP_ID ACTION_NAME

For the script file described in the above example, this command would look as follows:

php /var/www/wa/cli.php mail Check

Calling your script via the command line will help you test its operability.

Adding a script to a cron job

To make a script be executed periodically, add a line with its path and parameters to the cron's configuration file; e.g.:

*/10 * * * * /usr/bin/php /var/www/wa/cli.php mail Check

Read more about setting up cron jobs in article Cron setup.

Adding a note for application users

To facilitate setup of cron jobs for the users of your application, it is advisable to create file wa-apps/APP_ID/lib/config/cron.php with cron setup instructions in the following form:

<?php 

return array(
         'key' => 'cron configuration string'
);

Example:

<?php 

return array(
   'check_mail'=>'*/10 * * * * /usr/bin/php -q '.wa()->getConfig()->getPath('root').DIRECTORY_SEPARATOR.'cli.php mail Check',
);

To class Config of your application (wa-apps/APP_ID/lib/config/[APP_ID]Config.class.php) you can add method getCronJob:

public function getCronJob($name = null)
{
    static $tasks;
    if (!isset($tasks)) {
        $tasks = array();
        $path = $this->getAppConfigPath('cron');
        if (file_exists($path)) {
            $tasks = include($path);
        } else {
        $tasks = array();
        }
    }
    return $name?(isset($tasks[$name])?$tasks[$name]:null):$tasks;
}

Now you can display a useful note for the application administrator in the appropriate place:

For correct functioning of the application set up cron by adding the following cron job:
$this->getConfig()->getCronJob('check_mail')

This code will return the corresponding cron setup string:

*/10 * * * * /usr/bin/php -q /var/www/wa/cli.php mail Check

Notes for users of shared web hosting

PHP version used in the command line

On some web-hosting servers PHP files are be default handled by PHP 4, but the framework requires only PHP5.

In this case you need to replace /usr/bin/php with the path to the execution file of PHP5, which you can learn from your web-hosting company support team.

Folder permissions

It is advisable to run cron jobs on behalf of the same user, which is used to run the web server. This will help avoid permissions-related problems with folder wa-cache and other framework folders.

This issue is not relevant to most popular web-hosting servers. However, if you are using a VPS, then you need to specify the appropriate user name in the cron configuration line; e.g., www-data:

*/10 * * * * www-data /usr/bin/php -q /var/www/wa/cli.php mail Check