Merge pull request #9 from DavidLambauer/cron

added cron docs

Author: DavidLambauer

cron-jobs.md

@@ -0,0 +1,181 @@
+# Cron Jobs in Magento 2
+
+- [Introduction](#introduction)
+- [Setting up a Cron Job](#setting-up-a-cron-job)
+  - [Step 1: Declare the Cron Job in `crontab.xml`](#step-1)
+  - [Step 2: Define the Cron Job Method](#step-2)
+- [Executing a Cron Job](#executing-a-cron-job)
+- [Viewing and Managing Cron Tasks](#viewing-and-managing-cron-tasks)
+- [Cron Groups](#cron-groups)
+  - [Defining a Cron Group](#defining-a-cron-group)
+  - [Running a Specific Cron Group](#running-a-specific-cron-group)
+  - [Benefits of Using Cron Groups](#benefits-of-using-cron-groups)
+- [Best Practices for Cron Jobs](#best-practices-for-cron-jobs)
+
+<a href="#introduction"></a>
+## Introduction
+
+Cron jobs are scheduled tasks that run automatically at specified intervals. Magento uses cron jobs to run tasks such as
+reindexing, generating reports, sending newsletters, and many more. Cron jobs are essential to keep your Magento 2 store
+functioning correctly.
+
+<a href="#setting-up-a-cron-job"></a>
+## Setting up a Cron Job
+
+Setting up a cron job in Magento involves two main steps: declaring the cron job in the `crontab.xml` file, and defining
+the method that will be executed when the cron job runs.
+
+<a href="#step-1"></a>
+### Step 1: Declare the Cron Job in `crontab.xml`
+
+First, we need to declare our cron job in a `crontab.xml` file. This file should be located in the `etc` directory of
+your module. If it doesn't exist, create one.
+
+The syntax of the `crontab.xml` file is as follows:
+
+```xml
+<?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="my_cronjob" instance="Vendor\Module\Cron\Test" method="execute">
+            <schedule>* * * * *</schedule>
+        </job>
+    </group>
+</config>
+```
+
+In the above code:
+
+- `job name`: It's an identifier for your cron job.
+- `instance`: This is the class in your module that will be invoked when the cron job runs.
+- `method`: This is the method in your class that will be called.
+- `schedule`: This determines how often your cron job will run, based on cron syntax.
+
+<a href="#step-2"></a>
+### Step 2: Define the Cron Job Method
+
+Now, we need to create the cron class in the `Vendor\Module\Cron` directory and define the `execute()` method. This is
+the method that will be executed when the cron job runs.
+
+Here is an example of how to define this method:
+
+```php
+<?php
+namespace Vendor\Module\Cron;
+
+use \Psr\Log\LoggerInterface;
+
+class CronLogger
+{
+    protected $logger;
+
+    public function __construct(LoggerInterface $logger) {
+        $this->logger = $logger;
+    }
+
+    public function execute() {
+        $this->logger->info('Cron job has executed successfully!');
+        return $this;
+    }
+}
+```
+
+In this class:
+
+The `LoggerInterface` is used to log messages. The `execute()` method logs a message when the cron job runs
+successfully.
+
+<a href="#executing-a-cron-job"></a>
+## Executing a Cron Job
+
+To execute all Magento cron jobs, you run the following command in the terminal:
+
+```bash
+php bin/magento cron:run
+```
+
+This command will execute all cron jobs that are scheduled to run at the time the command is executed.
+
+<a href="#viewing-and-managing-cron-tasks"></a>
+## Viewing and Managing Cron Tasks
+
+To view a list of all scheduled cron jobs and their status, you can use the following command:
+
+```bash
+php bin/magento cron:status
+```
+
+This command will display a table containing information about each cron job, including the job code, status, created
+date, scheduled date, executed date, and finished date.
+
+If you need to remove a specific job from the cron schedule, you can do so with the following command:
+
+```bash
+php bin/magento cron:remove <job_code>
+```
+
+Replace `<job_code>` with the code of the job you wish to remove.
+
+<a href="#cron-groups"></a>
+## Cron Groups
+
+Magento 2 uses cron groups to manage related tasks together. A cron group is a set of cron jobs that are managed as a
+unit. All cron jobs in a group will run in the same process to ensure the resources are effectively used.
+
+<a href="#defining-a-cron-group"></a>
+### Defining a Cron Group
+
+Cron groups are defined in the `crontab.xml` file in the same way as individual cron jobs. The `group id` attribute is
+used to define the group. Jobs within the same group are enclosed within the same `group` tags.
+
+Here is an example of how to define a cron group:
+
+```xml
+<?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="my_cron_group">
+        <job name="my_cronjob1" instance="Vendor\Module\Cron\Test1" method="execute">
+            <schedule>* * * * *</schedule>
+        </job>
+        <job name="my_cronjob2" instance="Vendor\Module\Cron\Test2" method="execute">
+            <schedule>* * * * *</schedule>
+        </job>
+    </group>
+</config>
+```
+
+In this example, both `my_cronjob1` and `my_cronjob2` are part of `the my_cron_group group`.
+
+<a href="#running-a-specific-cron-group"></a>
+### Running a Specific Cron Group
+
+To run all jobs in a specific cron group, use the following command:
+
+```bash 
+php bin/magento cron:run --group="my_cron_group"
+```
+
+This command will run all cron jobs in `the my_cron_group group`.
+
+<a href="#benefits-of-using-cron-groups"></a>
+### Benefits of Using Cron Groups
+
+Using cron groups provides a few benefits:
+
+You can manage related cron jobs together, making your cron configuration easier to understand and maintain.
+You can run all jobs in a group simultaneously, which can lead to more efficient use of server resources.
+If an error occurs in one job, it won't affect the other jobs in the group.
+Remember, the effective management of cron jobs, including the use of cron groups, is vital for maintaining the
+performance and functionality of your Magento 2 store.
+
+<a href="#best-practices-for-cron-jobs"></a>
+## Best Practices for Cron Jobs
+
+- Always log the start, end, and any exceptions in your cron jobs. This will help in debugging issues later.
+- Always return $this at the end of your cron job method to ensure that the method chain isn't broken.
+- Don't overload your server with too many simultaneous cron jobs. Schedule your jobs efficiently to avoid high server
+  load.
+- Keep the execution time of your cron jobs as short as possible. Long-running jobs can slow down the overall
+  performance of your Magento store.