Magento 2.1.18 is the final 2.1.x release. After June 2019, Magento 2.1.x will no longer receive security patches, quality fixes, or documentation updates.
To maintain your site's performance, security, and PCI compliance, upgrade to the latest version of Magento.

Configure a custom cron job and cron group (tutorial)

This tutorial shows you step-by-step how to create a custom cron job and optionally a cron group in a sample module. You can use a module you already have or you can use a sample module from our magento2-samples repository.

Running the cron job results in a row being added to the cron_schedule table with the name of the cron job, custom_cron.

We also show you how to optionally create a cron group, which you can use to run custom cron jobs with settings other than Magento application defaults.

In this tutorial, we assume the following:

  • The Magento application is installed in /var/www/html/magento2
  • Your Magento database username and password are both magento
  • You perform all actions as the Magento file system owner

Step 1: Get a sample module

To set up a custom cron job, you need a sample module. We suggest the magento-module-minimal module.

If you already have a sample module, you can use it; skip this step and the next step and continue with Step 3: Create a class to run cron.

To get a sample module:
  1. Log in to your Magento server as, or switch to, the Magento file system owner.
  2. Change to a directory that is not in your Magento application root (for example, your home directory).

  3. Clone the magento2-samples repository.

    For example,

    1
2

    cd ~
git clone git@github.com:magento/magento2-samples.git

    If the command fails with the error Permission denied (publickey)., you must add your SSH public key to GitHub.com.

  4. Make a directory to which to copy the sample code:

    1

    mkdir -p /var/www/html/magento2/app/code/Magento/SampleMinimal

  5. Copy the sample module code:

    1

    cp -r ~/magento2-samples/sample-module-minimal/* /var/www/html/magento2/app/code/Magento/SampleMinimal

  6. Verify the files copied properly:

    1

    ls -al /var/www/html/magento2/app/code/Magento/SampleMinimal

    You should see the following result:

    1
2
3
4
5
6
7
8
9

    drwxrwsr-x.   4 magento_user apache  4096 Oct 30 13:19 .
drwxrwsr-x. 121 magento_user apache  4096 Oct 30 13:19 ..
-rw-rw-r--.   1 magento_user apache   372 Oct 30 13:19 composer.json
drwxrwsr-x.   2 magento_user apache  4096 Oct 30 13:19 etc
-rw-rw-r--.   1 magento_user apache 10376 Oct 30 13:19 LICENSE_AFL.txt
-rw-rw-r--.   1 magento_user apache 10364 Oct 30 13:19 LICENSE.txt
-rw-rw-r--.   1 magento_user apache  1157 Oct 30 13:19 README.md
-rw-rw-r--.   1 magento_user apache   270 Oct 30 13:19 registration.php
drwxrwsr-x.   3 magento_user apache  4096 Oct 30 13:19 Test

  7. Update the Magento database and schema:

    1

    bin/magento setup:upgrade

  8. Clean the cache:

    1

    bin/magento cache:clean

Step 2: Verify the sample module

Before you continue, make sure the sample module is registered and enabled.

To verify the sample module:
  1. Log in to the Magento Admin as an administrator.
  2. Click Stores > Settings > Configuration > ADVANCED > Advanced.

  3. In the right pane, under Disable Modules Output, look for Magento_SampleMinimal as the following figure shows.

    Verify your sample module

If the module doesn’t display, review step 1 carefully. Make sure your code is in the correct directory. Spelling and case are important; if anything is different, the module won’t load. Also, don’t forget to run magento setup:upgrade.

Step 3: Create a class to run cron

This step shows a simple class to create a cron job. The class only writes a row to the cron_schedule table that confirms it’s set up successfully.

To create a class:

  1. Create a directory for the class and change to that directory:

    1

    mkdir /var/www/html/magento2/app/code/Magento/SampleMinimal/Cron && cd /var/www/html/magento2/app/code/Magento/SampleMinimal/Cron

  2. Created a file named Test.php in that directory with the following contents:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

<?php
namespace Magento\SampleMinimal\Cron;
use \Psr\Log\LoggerInterface;

class Test {
    protected $logger;

    public function __construct(LoggerInterface $logger) {
        $this->logger = $logger;
    }

/**
   * Write to system.log
   *
   * @return void
   */

    public function execute() {
        $this->logger->info('Cron Works');
    }

}

Step 4: Create crontab.xml

crontab.xml sets a schedule to run your custom cron code.

To create crontab.xml:

Create crontab.xml as follows in the /var/www/html/magento2/app/code/Magento/SampleMinimal/etc directory:

1
2
3
4
5
6
7
8

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/crontab.xsd">
    <group id="default">
        <job name="custom_cronjob" instance="Magento\SampleMinimal\Cron\Test" method="execute">
            <schedule>* * * * *</schedule>
        </job>
    </group>
</config>

The preceding crontab.xml runs the Magento/SampleMinimal/Cron/Test.php class once per minute, resulting in a row being added to the cron_schedule table.

Step 5: Verify the cron job

This step shows how to verify the custom cron job successfully using a SQL query on the cron_schedule database table.

To verify cron:

  1. Run Magento cron jobs:

    1

    php /var/www/html/magento2/bin/magento cron:run

  2. Enter the magento cron:run command two or three times.

    The first time you enter the command, it queues jobs; subsequently, the cron jobs are run. You must enter the command at least twice.

  3. Run the SQL query SELECT * from cron_schedule WHERE job_code like '%custom%' as follows:

    1. Enter mysql -u magento -p
    2. At the mysql> prompt, enter use magento;
    3. Enter SELECT * from cron_schedule WHERE job_code like '%custom%';

    The result should be similar to the following:

    1
2
3
4
5
6
7
8

    +-------------+----------------+---------+----------+---------------------+---------------------+---------------------+---------------------+
| schedule_id | job_code       | status  | messages | created_at          | scheduled_at        | executed_at         | finished_at         |
+-------------+----------------+---------+----------+---------------------+---------------------+---------------------+---------------------+
|        3670 | custom_cronjob | success | NULL     | 2016-11-02 09:38:03 | 2016-11-02 09:38:00 | 2016-11-02 09:39:03 | 2016-11-02 09:39:03 |
|        3715 | custom_cronjob | success | NULL     | 2016-11-02 09:53:03 | 2016-11-02 09:53:00 | 2016-11-02 09:54:04 | 2016-11-02 09:54:04 |
|        3758 | custom_cronjob | success | NULL     | 2016-11-02 10:09:03 | 2016-11-02 10:09:00 | 2016-11-02 10:10:03 | 2016-11-02 10:10:03 |
|        3797 | custom_cronjob | success | NULL     | 2016-11-02 10:24:03 | 2016-11-02 10:24:00 | 2016-11-02 10:25:03 | 2016-11-02 10:25:03 |
+-------------+----------------+---------+----------+---------------------+---------------------+---------------------+---------------------+

  4. (Optional) Verify messages are written to Magento’s system log:

    1

    cat /var/www/html/magento2/var/log/system.log

    You should see one or more entries like the following:

    1

    [2016-11-02 22:17:03] main.INFO: Cron Works [] []

    These messages come from the execute method in Test.php:

    1
2

    public function execute() {
   $this->logger->info('Cron Works');

If the SQL command and system log contain no entries, run the magento cron:run command a few more times and wait. It can take some time for the database to update.

Step 6 (optional): Set up a custom cron group

This step shows how to optionally set up a custom cron group. You should set up a custom cron group if you want your custom cron job to run on a different schedule than other cron jobs (typically, once per minute) or if you want several custom cron jobs to run with different settings.

To set up a custom cron group:
  1. Open crontab.xml in a text editor.
  2. Change <group id="default"> to <group id="custom_crongroup">
  3. Exit the text editor.
  4. Create /var/www/html/magento2/app/code/Magento/SampleMinimal/etc/cron_groups.xml with the following contents:
1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Cron:etc/cron_groups.xsd">
    <group id="custom_crongroup">
        <schedule_generate_every>1</schedule_generate_every>
        <schedule_ahead_for>4</schedule_ahead_for>
        <schedule_lifetime>2</schedule_lifetime>
        <history_cleanup_every>10</history_cleanup_every>
        <history_success_lifetime>60</history_success_lifetime>
        <history_failure_lifetime>600</history_failure_lifetime>
        <use_separate_process>1</use_separate_process>
    </group>
</config>

For a description of what the options mean, see Configure custom cron jobs and cron groups reference.

Step 7 (optional): Verify your custom cron group

This step shows how to verify your custom cron group using the Magento Admin.

To verify your custom cron group:

  1. Run Magento cron jobs for your custom group:

    1

    php /var/www/html/magento2/bin/magento cron:run --group="custom_crongroup"

    Run the command at least twice.

  2. Clean the Magento cache:

    1

    php /var/www/html/magento2/bin/magento cache:clean
  3. Log in to the Magento Admin as an administrator.
  4. Click Stores > Settings > Configuration > Advanced > System.

  5. In the right pane, expand Cron.

    Your cron group displays as follows:

    Your custom cron group

Updated
© 2023 Magento. All rights reserved.