Webasyst Cron

Regular execution of repeated tasks without user involvement.

The Webasyst Cron service allows your app to run recurrent actions without user involvement (e.g., data syncing, outdated cache clearing, notifications sending, etc.). This helps to avoid manually configuring the server scheduler in the control panel.

The service is available only if connection to Webasyst ID is enabled in the system settings.

How it works

Your app schedules a new job with the required frequency by sending a special request to Webasyst Cron.

This is similar to manually setting up a Cron job in the server control panel.
Webasyst Cron sends repeated HTTP requests to the user account, where the Webasyst framework routes those requests to the PHP classes of jobs implemented in your app.

This is similar to the execution of a configured job by an ordinary sever scheduler.
If you need to cancel a job then send another request to Webasyst Cron to remove the specified job from the list of active ones.

This is similar to deleting a scheduler job via the control panel.

1. Create a configuration file

Add file lib/config/cron.php to your app’s source. Add the execution frequency and other parameters of each job:

return [
    'job-1' => [
        'expression' => '*/6 * * * *',    // execute every 6 minutes
        'action' => 'example'    // job ID
    ],
    'job-2' => [
        'expression' => '* * * * *',    // execute every minute
        'action' => 'other',    // job ID
        'params' => [    // extra parameters
            'foo' => 'bar'
        ]
    ],
    // ...
];

Job configuration values

expression
Execution frequency in the standard Cron format.
action
Unique job identifier within your app.
params
Optional associative array of parameters passed on to the job’s PHP class.

Array keys can be used, for instance, for convenient access to a selected configuration entry.

2. Create jobs’ PHP classes

The execution logic of each job must be implemented in a separate class:

File name: [app_id][Job_id].cron.php.
Class name: [app_id][Job_id]Cron.
Base class: must inherit system class waCronExecutor.

The entry point of each job must be public method execute($params).

Example

<?php

class myappExampleCron extends waCronExecutor
{
    /**
    * @param array $params Value of 'params' key from cron.php
    */
    public function execute($params)
    {
        // Your business logic
        $foo = $params['foo'] ?? null;
    }
}

3. Implement job handling

For sending requests to Webasyst Cron, system class waServicesApi is used, which returns an installerServicesApi object with the following public methods:

schedule
Enables a job.
deleteJob
Cancels a job.
getJobs
Returns the list of enabled jobs.

Reading app jobs configuration

Use the call of the following system method:

wa([app_id])->getConfig()->getCron()

public function schedule ($cron_expression, $action, $app_id)

Enables an app job.

Params

$cron_expression
String value specifying the job execution frequency in the standard Cron format.
$action
Job ID.
$app_id
App ID.

Example

$cron_config = wa($app_id)->getConfig()->getCron();

$cron_action = '...';    // job_id

/** @var installerServicesApi */
$api = new waServicesApi();

$result = $api->schedule(
    $cron_config[$cron_action]['expression'],
    $cron_action,
    wa()->getApp()
);

public function deleteJob ($action, $app_id)

Cancels an app job.

Params

$action
Job ID.
$app_id
APp ID.

Example

/** @var installerServicesApi */
$api = new waServicesApi();
$result = $api->deleteJob($cron_action, wa()->getApp());

public function getJobs ($app_id)

Returns the list of the app’s enabled jobs.

Params

$app_id
App ID.

Example

/** @var installerServicesApi */
$api = new waServicesApi();
$result = $api->getJobs(wa()->getApp());

How to configure a job manually (in the server control panel)

If you need to avoid calling system method schedule().

To do so, set up a server scheduler job using a command according to the following pattern:

php cli.php --cron [app_id] [job_id]