Cron

Contao periodically executes some tasks via its own cron functionality. These include mainly cleanup tasks such as

• Purge expired comment subscriptions
• Purge expired registrations
• Purge expired Opt-In tokens
• etc.

since 5.0 Starting with Contao 5 all cronjobs are registered as services and tagged using the contao.cronjob tag. Thus you can find all cronjobs on your system using the following command:

$ vendor/bin/contao-console debug:container --tag contao.cronjob

since 5.3 Starting also with Contao 5.3 you will find a special contao.cron.supervise_workers cronjob. This cronjob will automatically start worker processes for the asynchronous messaging feature. There is, however, a fallback in case you do not configure a proper contao:cron cronjob (see next section). Then all messages (from the default Contao Managed Edition message queues) will be processed within kernel.terminate of the web process.

Configuring the Cron Job

By default the cron tasks are executed after a response is sent back to the visitor when a request to the Contao site has been made.

In Contao 4 you can disable the front end cron by going to System » Settings » Cron job settings and enabling the setting Disable the command scheduler. You can also force this setting via your application’s config:

# config/config.yaml
contao:
    localconfig:
        disableCron: true

After disabling the front end cron you should periodically let Contao execute its cron jobs, either via the command line (recommended) or by making a request to the web URL.

since 5.1 Starting with version 5.1 Contao detects whether a real cron job is executed or not and thus disables the front end cron automatically if applicable. However, you can modify this behavior via the following configuration:

# config/config.yaml
contao:
    cron:
        web_listener: false

The default value is 'auto'.

Command Line

Executing the cron jobs via the command line is done via the contao:cron command:

$ vendor/bin/contao-console contao:cron

This is also the recommended way of periodically executing Contao’s cron jobs. In a Linux crontab you could use the following instructions for example:

* * * * * /usr/bin/php /path/to/contao/vendor/bin/contao-console contao:cron

# config/parameters.yaml
parameters:
    router.request_context.host: 'example.org'
    router.request_context.scheme: 'https'

since 5.0 You are also able to force the the execution of cron jobs via the --force parameter:

$ vendor/bin/contao-console contao:cron --force

since 5.0 You can also execute just one specific cron job from the command line:

$ vendor/bin/contao-console contao:cron "App\Cron\ExampleCron"

The latter can also be combined with the --force option.

Web URL

In order to trigger the execution of cron jobs via a web URL, a request to the _contao/cron route, e.g. https://example.org/_contao/cron, needs to be made. In a Linux crontab you could use the following instructions for example:

* * * * * wget -q -O /dev/null https://example.org/_contao/cron

Registering Cron Jobs

Registering custom cron jobs is similar to registering to hooks. As of Contao 4.13, there are four different ways of registering a cron job. The recommended way is using PHP attributes. Which one you use depends on your setup. For example, if you still need to support PHP 7 you can use annotations. If you still develop cron jobs for Contao 4.4 then you still need to use the PHP array configuration.

Generally cron jobs can be registered through the contao.cronjob service tag. The following options are supported for this service tag:

// src/Cron/ExampleCron.php
namespace App\Cron;

use Contao\CoreBundle\DependencyInjection\Attribute\AsCronJob;

#[AsCronJob('hourly')]
class ExampleCron
{
    public function __invoke()
    {
        // Do something …
    }
}

// src/Cron/ExampleCron.php
namespace App\Cron;

use Contao\CoreBundle\ServiceAnnotation\CronJob;

/** 
 * @CronJob("hourly")
 */
class ExampleCron
{
    public function __invoke()
    {
        // Do something …
    }
}

# config/services.yaml
services:
    App\Cron\ExampleCron:
        tags:
            - { name: contao.cronjob, interval: hourly }

// src/Cron/ExampleCron.php
namespace App\Cron;

class ExampleCron
{
    public function __invoke()
    {
        // Do something …
    }
}

// contao/config/config.php
$GLOBALS['TL_CRON']['hourly'][] = [\App\Cron\ExampleCron::class, 'onHourly'];

// src/Cron/ExampleCron.php
namespace App\Cron;

class ExampleCron
{
    public function onHourly(): void
    {
        // Do something …
    }
}

Scope

In some cases a cron job might want to know in which “scope” it is executed in - i.e. as part of a front end request or as part of the cron command on the command line interface. The Cron service will pass a scope parameter to the cron job’s method.

// src/Cron/HourlyCron.php
namespace App\Cron;

use Contao\CoreBundle\Cron\Cron;
use Contao\CoreBundle\DependencyInjection\Attribute\AsCronJob;
use Contao\CoreBundle\Exception\CronExecutionSkippedException;

#[AsCronJob('hourly')]
class HourlyCron
{
    public function __invoke(string $scope): void
    {
        // Skip this cron job in the web scope
        if (Cron::SCOPE_WEB === $scope) {
            throw new CronExecutionSkippedException();
        }

        // …
    }
}

Asynchronous cron jobs

The cron job framework executes jobs synchronously in the order they were tagged (normal service priority tags). This means that if you e.g. have 10 cron jobs, and they all take 20 seconds to run, it will take the framework 200 seconds to complete. For most cron jobs, this is not a problem because they don’t usually run 20 seconds.

However, if you have cron jobs that trigger child processes or are asynchronous in any other way, you would want them to start immediately in parallel without blocking the other cron jobs. You can do this by returning a GuzzleHttp\Promise\PromiseInterface:

// src/Cron/HourlyCron.php
namespace App\Cron;

use Contao\CoreBundle\Cron\Cron;
use Contao\CoreBundle\DependencyInjection\Attribute\AsCronJob;
use Contao\CoreBundle\Exception\CronExecutionSkippedException;
use GuzzleHttp\Promise\Promise;
use GuzzleHttp\Promise\PromiseInterface;

#[AsCronJob('hourly')]
class HourlyCron
{
    public function __invoke(string $scope): PromiseInterface
    {
        // Skip this cron job in the web scope
        if (Cron::SCOPE_WEB === $scope) {
            throw new CronExecutionSkippedException();
        }

        return $promise = new Promise(static function () use (&$promise): void {
            // Do something that is asynchronous
            $promise->resolve('Done with asynchronous process.');
        });
    }
}

Because most asynchronous processes are most likely things like a spawned child process using Symfony’s Process component, Contao also provides a utility service for that:

// src/Cron/HourlyCron.php
namespace App\Cron;

use Contao\CoreBundle\Cron\Cron;
use Contao\CoreBundle\DependencyInjection\Attribute\AsCronJob;
use Contao\CoreBundle\Exception\CronExecutionSkippedException;
use Contao\CoreBundle\Util\ProcessUtil;
use GuzzleHttp\Promise\PromiseInterface;

#[AsCronJob('hourly')]
class HourlyCron
{
    public function __construct(private ProcessUtil $processUtil) {}

    public function __invoke(string $scope): PromiseInterface
    {
        // Skip this cron job in the web scope
        if (Cron::SCOPE_WEB === $scope) {
            throw new CronExecutionSkippedException();
        }

        // Long-running process - probably not "ls" :-)
        $promise = $this->processUtil->createPromise(new Process(['ls']));
        
        // There's even a helper for another application command, so you don't have to worry about
        // finding the right PHP binary etc.:
        $promise = $this->processUtil->createPromise(
            $this->processUtil->createSymfonyConsoleProcess('app:my-command', '--option-1', 'argument-1')
        );
        
        return $promise;
    }
}

Testing

Contao keeps track of a cronjob’s last execution in the tl_cron_job table. Thus, if you want to test a cron job even though it has already been executed within its defined interval, either truncate the whole table or delete the entry for the specific cron job you want to test. If the table is empty every cronjob will be executed on the first cron call. After that only on its defined interval.

vendor/bin/contao-console doctrine:query:sql "TRUNCATE tl_cron_job"