Festi Cron

Festi Cron is a powerful task scheduling and job queue management library for the Festi Framework. It provides support for scheduled cron jobs, queue-based execution, and Kafka integration for distributed task processing.

Installation

To install Festi Cron using Composer, add the following to your composer.json file:

{
    "require": {
        "festi-team/festi-framework-cron": "dev-develop"
    }
}

Then, run:

composer install

Features

  • Scheduler Worker – Manage and execute scheduled tasks efficiently.
  • Queue-based Execution – Process tasks in the background using job queues.
  • Singleton Workers – Ensure that a cron job does not run multiple times simultaneously.
  • Kafka Integration – Use Kafka-based queue processing for distributed workloads.
  • RabbitMQ Integration – Use AMQP-based queue processing via php-amqplib.
  • Exception Handling – Prevent execution conflicts and errors with built-in exception management.

Usage

1. Defining a Cron Job

Create a worker by extending the CronWorker class:

use core\cron\CronWorker;

class MyCronJob extends CronWorker
{
    public function onStart(): void
    {
        // Your cron task logic here
        echo "Executing MyCronJob...";
    }
}

2. Running a Cron Job

To execute a cron job manually:

$worker = new MyCronJob();
$worker->start();

3. Using Queue Workers

CREATE TABLE IF NOT EXISTS `queue_[TYPE]` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `data` longtext NOT NULL,
  `error` longtext NULL DEFAULT NULL,
  `id_worker` int(10) unsigned DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8

To handle queued execution:

use cron\CronQueueWorker;

class MyQueueJob extends CronQueueWorker
{
    public function onStart(): void
    {
        echo "Processing queued job...";
    }


}

Register and run:

$worker = new MyQueueJob();
$worker->enqueue();

4. Singleton Execution

Ensure a job runs only once at a time:

use cron\CronSingletonWorker;

class BankTransferAccountsSyncCronWorker extends CronSingletonWorker
{
    /**
     * @override
     */
    public function start(): void
    {
        $plugin = Core::getInstance()->getPluginInstance('Payments');
        assert($plugin instanceof PaymentsPlugin);

        $plugin->syncWithServices();
    }
}

try {
    $worker = new BankTransferAccountsSyncCronWorker();
    $worker->start();

} catch (AlreadyRunningCronWorkerException $alreadyExp) {
    exit(0);
} catch (Exception $exp) {
    FestiUtils::doHandleCoreException($exp);
}
use cron\CronSingletonWorker;

class MoneyReportCronWorker extends CronSingletonWorker
{

    protected StaffPlugin $userPlugin;

    protected FinancePlugin $financePlugin;

    /**
     * @override
     */
    protected function onStart(): void
    {
        $core = Core::getInstance();

        $this->userPlugin = $core->getPluginInstance('Staff');
        $this->financePlugin = $core->getPluginInstance('Finance');
    } // end onStart

    /**
     * @override
     */
    protected function onRow(mixed $data): void
    {
        $userValuesObject = new UserValuesObject($data);

        $this->financePlugin->onCalculateUserMonthlyPayment(
            $userValuesObject, 
            date(static::DATA_FORMAT)
        );
    }

    /**
     * @override
     */
    protected function onRowError(mixed $record, Throwable $exp): void
    {
        $values = array(
            MoneyTransferValuesObject::FIELD_STATUS => MoneyTransferValuesObject::STATUS_ERROR,
            MoneyTransferValuesObject::FIELD_ERROR  => $exp->getMessage()
        );

        $this->financePlugin->updateMoneyTransfer($values, $record['id']);

        throw $exp;
    }

    /**
     * @override
     */
    protected function getSpool(): ?array
    {
        $search = array(
            'salary&IS NOT' => 'NULL',
            'hire_date&<=' => date('Y-m-t', $this->_currentTime),
            'sql_or' => array(
                array('fired&IS' => 'NULL'),
                array('fired&>=' => date(static::DATA_FORMAT, $this->_currentTime))
            )
        );

        return $this->userPlugin->search($search);
    }
}

try {
    $worker = new MoneyReportCronWorker();
    $worker->start();
} catch (Exception $exp) {
    FestiUtils::doHandleCoreException($exp);
}
class СabinetsOrderSyncQueue extends CronQueueSingletonWorker
{

    public function getStorageName(): string
    {
        return 'queue_cabinets_order_sync';
    }

    protected function onRow(mixed $record): void
    {
        $data = json_decode($record['data'], true);

        $plugin = Controller::getInstance()->getPluginInstance("CabinetOrders");
        $plugin->onTaskOrderSync($data);
    }

    protected function onDelay(): void
    {
        sleep(60);
    }
}

$worker = new СabinetsOrderSyncQueue($controller->db);
$worker->start();

5. Kafka Worker

Install PHP Kafka Driver

  1. Install C/C++ Driver
git clone https://github.com/edenhill/librdkafka.git
cd librdkafka
./configure
make
sudo make install
  1. Install php-rdkafka
pecl install rdkafka

Used

class TestWorker extends KafkaCronWorker
{
    protected function onRow(mixed $record): void
    {
        print_r($record);
    }
}

$worker = new TestWorker();
$worker->start();
php test_kafka.php --brokers 78.46.49.42 --topic test --id g1
echo "Hello, World" | ~/kafka/bin/kafka-console-producer.sh --broker-list 78.46.49.42:9092 --topic test > /dev/null
class StatisticsWorker extends KafkaCronQueueSingletonWorker
{
    const TIMEOUT = 100;
    const FILE_NAME_OFFSET_POSTFIX   = 'offset';
    const DEFAULT_OFFSET_VALUE       = '0';
    const FILE_NAME_OFFSET_DELIMITER = '-';
    const REGEXP_DUPLICATE_EXCEPTION = '#duplicate key value violates#Umis';

    protected ?StatisticsPlugin $plugin = null;

    protected function onStart(): void
    {
        $file = $this->_getOffsetFilePath();

        if (!file_exists($file)) {
            $this->_onPrepareFileOffset($file);
        }

        $result = file_get_contents($file);

        if (!$result) {
            $this->_onPrepareFileOffset($file);
        }
    }

    protected function onRow(mixed $record): void
    {
        $this->plugin->onTaskAddStats($record);
    }

    protected function getConsumerConfig(): RdKafka\Conf
    {
        $conf = new RdKafka\Conf();

        $conf->set('max.partition.fetch.bytes', 100);
        $conf->set('security.protocol', 'ssl');
        $conf->set(
            'ssl.ca.location',
            KAFKA_SSL_CERT_PATH.'kafka_trust_cert.pem'
        );
        $conf->set(
            'ssl.certificate.location',
            KAFKA_SSL_CERT_PATH.'kafka_client_cert.pem'
        );
        $conf->set(
            'ssl.key.location',
            KAFKA_SSL_CERT_PATH.'kafka_client_cet_key.pem'
        );

        $conf->set('group.id', (string) $this->getOption('id'));

        return $conf;
    } // end getConsumerConfig


    protected function getTopicConfig(): RdKafka\TopicConf
    {
        $topicConf = new RdKafka\TopicConf();
        $topicConf->set('auto.commit.interval.ms', (string) static::AUTOCOMMIT_TIMEOUT);

        // Set the offset store method to 'file'
        $topicConf->set('offset.store.method', 'file');
        $topicConf->set('offset.store.path', sys_get_temp_dir());

        return $topicConf;
    } // end getTopicConfig

    protected function onSpoolStart(): void
    {
        $this->plugin = $this->_getStatisticsPlugin();
    } // end onSpoolStart

    protected function onRowError(mixed $record, Throwable $exp): void
    {
        $msg = $exp->getMessage();

        if ($this->_isDuplicateKeyException($msg)) {
            return;
        }

        $this->_setOffsetToFile($record);

        throw $exp;
    } // end onRowError

    protected function onRowCompleted(mixed $record): void
    {
        $this->_setOffsetToFile($record);
    } // end onRowCompleted
}

6. RabbitMQ Worker

The RabbitMQ workers need the package php-amqplib/php-amqplib, which needs the PHP extension sockets. The package is optional: add it to the require of your project.

composer require php-amqplib/php-amqplib:^3.3

Single-queue consumer

use cron\RabbitMqCronWorker;

class OrderNotificationWorker extends RabbitMqCronWorker
{
    protected function onRow(mixed $record): void
    {
        $data = json_decode($record['data'], true);
        // process $data ...
    }
}

try {
    $worker = new OrderNotificationWorker();
    $worker->start();
} catch (\cron\AlreadyRunningCronWorkerException $e) {
    exit(0);
}
RABBITMQ_PASSWORD=secret php worker.php --host=localhost --queue=order_notifications --id=worker1

The password is required: set the environment variable RABBITMQ_PASSWORD (it wins) or pass --password. Without one the worker throws a CronException ("Undefined password"). Optional flags with defaults: --port (5672), --user (guest), --vhost (/).

Multi-queue consumer

Extend RabbitMqCronQueueWorker and pass a comma-separated list of queues. Each getSpool() call polls all queues in order.

use cron\RabbitMqCronQueueWorker;

class EventWorker extends RabbitMqCronQueueWorker
{
    protected function onRow(mixed $record): void
    {
        $queue = $record['queue']; // which queue this message came from
        $data  = json_decode($record['data'], true);
        // process $data ...
    }
}
php worker.php --host=localhost --queue=orders,payments,refunds --id=worker1

Multi-queue + singleton

Use RabbitMqCronQueueSingletonWorker to prevent duplicate processes. The lock file is keyed by class name and --id.

use cron\RabbitMqCronQueueSingletonWorker;

class PaymentWorker extends RabbitMqCronQueueSingletonWorker
{
    protected function onRow(mixed $record): void
    {
        // process payment message ...
    }
}

try {
    $worker = new PaymentWorker();
    $worker->start();
} catch (\cron\AlreadyRunningCronWorkerException $e) {
    exit(0);
}

SSL / custom connection

Override onInit() to use a custom connection class (e.g. AMQPSSLConnection):

use cron\RabbitMqCronWorker;
use PhpAmqpLib\Connection\AMQPSSLConnection;

class SecureWorker extends RabbitMqCronWorker
{
    protected function onInit(): void
    {
        if (!class_exists('PhpAmqpLib\\Connection\\AMQPSSLConnection')) {
            throw new \cron\CronException("Not found PHP package: php-amqplib/php-amqplib");
        }

        $this->connection = new AMQPSSLConnection(
            $this->getOption('host'),
            $this->getOption('port'),
            $this->getOption('user'),
            $this->getOption('password'),
            $this->getOption('vhost'),
            ['cafile' => '/path/to/ca.pem']
        );
        $this->channel = $this->connection->channel();
        $this->channel->queue_declare($this->getOption('queue'), false, true, false, false);
    }

    protected function onRow(mixed $record): void
    {
        // ...
    }
}

ACK / NACK behaviour

  • Success (onRowCompleted): message is ACKed and removed from the queue.
  • Error (onRowError): message is NACKed with requeue=false (routed to dead-letter exchange or discarded), then the exception is re-thrown. Override onRowError() to implement custom retry logic.

Stopping a Worker

CronWorker::start() catches SIGTERM and SIGINT (docker stop, kill, Ctrl+C). After the signal:

  1. The worker finishes the current row (onRow() and onRowCompleted() or onRowError()).
  2. It skips the other rows of the batch and runs onSpoolCompleted(). A CronQueueWorker deletes the done rows there, so no done row is processed again.
  3. The loop ends after onDelay(), start() returns, and the script exits with code 0. A signal during onDelay() stops the sleep() at once.

The signal handling needs the pcntl extension. Without it, the signals keep their default action: the process stops at once.

Only the loop of start() catches the signals. A worker that overrides start() (for example a one-shot CronSingletonWorker) keeps the default action. Override createStopSignalHandler() to change how a worker gets the stop signal.

Lock Directory

A singleton worker writes its PID to <lock directory>/<lock file name>.chk. The worker takes the first directory that is set:

  1. the option lock_dir (--lock_dir=/run/locks for a queue worker, or the options array);
  2. the environment variable FESTI_CRON_LOCK_DIR;
  3. getBaseLockPath() (default: locks/ next to the worker class).

The worker creates the directory if it does not exist. In a container, put it on a tmpfs.

A lock file counts as held only when its PID is a live process that is not the current process. A restarted container process often gets the same PID as before (for example 1), and then it takes the lock. The check uses posix_getpgid($pid) (it sends no signal), or /proc/<pid> without the posix extension, so the image needs no ps (procps).

Upgrading to the major version with native types

The classes of src/ declare strict_types=1 and native types. A subclass must declare the same types, or PHP stops with a fatal error when it loads the class:

Method or property Type
getOptions() ?array (array in the queue, Kafka, RabbitMQ and singleton workers)
getSpool() ?array (array in the queue, Kafka, RabbitMQ and singleton workers)
onRow($record) onRow(mixed $record): void
onRowCompleted($record) onRowCompleted(mixed $record): void
onRowError($record, $exp) onRowError(mixed $record, \Throwable $exp): void
onInit(), onStart(), onSpoolStart(), onSpoolCompleted(), onDelay(), start(), iteration() : void
getOption($key) getOption(string\|int $key): mixed
isRunning() : bool
getLockFileName(), getBaseLockPath() : string
CronQueueWorker::getErrorMessage($record, $exp) getErrorMessage(array $record, \Throwable $exp): string
CronQueueWorker::getProcessedRecords() : array
CronQueueWorker::$db, $processedStorageRecords \IDataAccessObject, array
CronWorkerManager::startProcess(), execProcess() (string $scriptPath): bool, (string $processCmd): bool
CronWorkerManager::getScreenPath(), getPhpPath() : string
KafkaCronWorker::$consumer, $listener ?\RdKafka\Consumer, \RdKafka\ConsumerTopic\|\RdKafka\Queue\|null
KafkaCronWorker::onInitConsumer(), onInitListener() : void
KafkaCronWorker::getRemoteMessage(), getTopicConfig(), getConsumerConfig() ?\RdKafka\Message, \RdKafka\TopicConf, \RdKafka\Conf
RabbitMqCronWorker::$connection, $channel ?\PhpAmqpLib\Connection\AbstractConnection, ?\PhpAmqpLib\Channel\AMQPChannel

A void hook returns no value: return true; or return false; in onStart(), onRow() or onRowError() becomes return;. CronQueueWorker::onSpoolCompleted() returned false when no row was processed; it returns nothing now.

Removed from CronWorker: isStopSignalReceived() (override hasNextIteration() or createStopSignalHandler()), getLockDirectory() (the lock directory is resolved in isRunning()), the constant POSIX_ERROR_EPERM (the PID check is in ProcessLock). createProvider() moved to CronQueueWorker. CronWorker::getLockFileName() returns lock_<class name> instead of throwing a CronException.

Two removals give no error. PHP loads a subclass that still overrides getLockDirectory() or isStopSignalReceived(), but nothing calls the override any more:

  • An override of getLockDirectory() is ignored, and the worker writes its .chk file to the option lock_dir, the variable FESTI_CRON_LOCK_DIR or getBaseLockPath(). A new process then does not see the lock of an old process in the old directory, and the two can run at the same time. Set the directory with the option lock_dir, the variable FESTI_CRON_LOCK_DIR or an override of getBaseLockPath() instead.
  • An override of isStopSignalReceived() is ignored, so the worker does not stop on its condition. Put the stop condition in an override of hasNextIteration() instead.

RabbitMQ password. RabbitMqCronWorker::DEFAULT_PASSWORD ('guest') is removed, and the RabbitMQ workers have no default password any more. A worker that relied on the default stops in getOptions() with the CronException "Undefined password". Set RABBITMQ_PASSWORD=guest or pass --password=guest to keep the old login. The defaults of port, user and vhost are applied in the new method applyOptionDefaults(array $options): array.

Before the upgrade, search your workers for the two names:

grep -rn "getLockDirectory\|isStopSignalReceived" path/to/your/workers

Best Practices

  • Use Singleton Workers to prevent duplicate executions.
  • Monitor Cron Logs to troubleshoot job failures.
  • Use Kafka or RabbitMQ for Distributed Jobs when scaling across multiple servers.
  • Define Execution Time Limits to avoid long-running tasks blocking the queue.