README

Introduction

This is a lightweight package for load balancing your cron tasks. It is used to distribute tasks across a network of identical servers to make sure they are run only once and not multiple times.

It is important that your application network uses only one single central mysql database. A table is created in the database in which current tasks are inserted. A primary key ensures that the task only runs once (a kind of locking process).

the unique_hash is a md5 hash of the task name, the schedule and the current timestamp without seconds. With this, the nodes can run asynchronously but the task runs only once at a time.

Scheme of operation

Requirements

• MySQL Database
• PHP PDO Extension (ext-pdo, ext-pdo_mysql)

1. Installation

1.1 Composer

Install Load Balanced Cron Task using Composer.

$ composer require incapption/load-balanced-cron-task

1.2 Create MySQL Table

This package needs a small table in your database. It's used for locking running tasks, to make sure that only on app instance could run it.

CREATE TABLE IF NOT EXISTS `lbct_tasks` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`unique_hash` varchar(32) NOT NULL,
`task` varchar(256) NOT NULL,
`schedule` varchar(256) NOT NULL,
`date_created` datetime NOT NULL,
`worker` varchar(256),
PRIMARY KEY (`unique_hash`),
KEY `id` (`id`)
);

1.3 Install Crontab

The idea is that you have only one single cron task running every minute. This cron task contains all other tasks wrapped by LoadBalancedCronTask

Open your crontab console (e.g. linux: crontab -e)

* * * * /usr/bin/php /your/local/path/cron.php

1.4 Create your cron file

Maybe you want to integrate into your application, or you create a new plain file.

<?php

use Incapption\LoadBalancedCronTask\Abstracts\CronTaskAbstract;
use Incapption\LoadBalancedCronTask\LoadBalancedCronTask;
use Incapption\LoadBalancedCronTask\Exceptions\LoadBalancedCronTaskException;

require_once('./vendor/autoload.php');

class TestCronTask extends CronTaskAbstract
{
    public function __construct()
    {
        $this->name = 'TestCronTask';
    }

    public function task(): bool
    {
        // do your cron task
        return file_put_contents('test.html', 'awesome! it works! '.date('Y-m-d H:i:s', time()));
    }
}

try {
    $response = (new LoadBalancedCronTask())
        ->mysql($_ENV['MYSQL_HOST'], $_ENV['MYSQL_USER'], $_ENV['MYSQL_PASSWORD'], $_ENV['MYSQL_DATABASE'])
        ->setWorkerName('Node 1')
        ->task((new TestCronTask()))
        ->loadBalanced()
        ->everyMinute()
        ->run();
} catch (LoadBalancedCronTaskException $e) {
    exit($e->getMessage());
}

2. How to use it

As shown in the example above you need to create classes for your cron tasks that extends CronTaskAbstract. Define the behavior in the task() method.

Second create the load balanced cron task.

# Example for a distributed load balanced cron task
 
$response = (new LoadBalancedCronTask())
    ->mysql($_ENV['MYSQL_HOST'], $_ENV['MYSQL_USER'], $_ENV['MYSQL_PASSWORD'], $_ENV['MYSQL_DATABASE'])
    ->setWorkerName('Node 1')
    ->task((new TestCronTask()))
    ->loadBalanced()
    ->everyMinute()
    ->run();

# Example for a local cron task
 
$response = (new LoadBalancedCronTask())
    ->task((new TestCronTask()))
    ->local()
    ->everyMinute()
    ->run();

2.1 Chainable methods

General:

Scheduling methods:

Be careful with the days 29th, 30th, 31st if you use monthlyOn(). Maybe use lastDayOfMonth() or lastDayOfMonthOffset() instead.

3. Exceptions

An instance of LoadBalancedCronTask() throws a LoadBalancedCronTaskException when there is something wrong inside the logic for everything else you can use the default PHP Exceptions.