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
git clone https://github.com/edenhill/librdkafka.git
cd librdkafka
./configure
make
sudo make install
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 withrequeue=false(routed to dead-letter exchange or discarded), then the exception is re-thrown. OverrideonRowError()to implement custom retry logic.
Stopping a Worker
CronWorker::start() catches SIGTERM and SIGINT (docker stop, kill, Ctrl+C). After the signal:
- The worker finishes the current row (
onRow()andonRowCompleted()oronRowError()). - It skips the other rows of the batch and runs
onSpoolCompleted(). ACronQueueWorkerdeletes the done rows there, so no done row is processed again. - The loop ends after
onDelay(),start()returns, and the script exits with code 0. A signal duringonDelay()stops thesleep()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:
- the option
lock_dir(--lock_dir=/run/locksfor a queue worker, or the options array); - the environment variable
FESTI_CRON_LOCK_DIR; 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.chkfile to the optionlock_dir, the variableFESTI_CRON_LOCK_DIRorgetBaseLockPath(). 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 optionlock_dir, the variableFESTI_CRON_LOCK_DIRor an override ofgetBaseLockPath()instead. - An override of
isStopSignalReceived()is ignored, so the worker does not stop on its condition. Put the stop condition in an override ofhasNextIteration()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.