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.

Cronjobs that are registered via the the contao.cronjob service tag can be listed using the following command:

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

However, keep in mind that this will not find cronjobs that are registered via the legacy config.php (see below). Unfortunately there is no convenient way in Contao 4 to display registered legacy cronjobs. If you want to look these up you could either search for any $GLOBALS['TL_CRON'] definitions in your Contao instance via your IDE, or use Xdebug for example in order to inspect the $GLOBALS['TL_CRON'] array.

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.

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'

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();
        }

        // …
    }
}

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"