Symfony Scheduler: Cron Jobs with the Messenger

1. Why classic cron jobs cause problems

Classic cron jobs, defined in the server's crontab, have a fundamental drawback: they exist outside the application. The logic lives in a Symfony command, but the schedule lives on the server. When the application migrates to a new server, every cron entry has to be transferred manually. When a developer changes the schedule, that change is nowhere visible in the repository. Code reviews only capture the command code, not the trigger time. These are exactly the scenarios where Symfony Scheduler makes the difference.

Another problem: cron jobs run independently of the Messenger stack. Retry logic, dead letter queues and monitoring are hard to retrofit onto cron-based tasks. If a cron job fails, that is often only visible at the next scheduled run. With Symfony Scheduler, periodic tasks are fully integrated into the Messenger: they benefit from automatic retries, failure transports and all the middleware features the Messenger provides. The result is background processing with unified monitoring and clear ownership in the PHP code.

2. The Scheduler concept in Symfony

The Symfony Scheduler, introduced in Symfony 6.3 and significantly extended in 7.x, is built on two core concepts: the Schedule class and the RecurringMessage. A Schedule class implements the ScheduleProviderInterface and defines in its getSchedule() method which messages should be sent when. Every message is a normal Symfony Messenger message object, processed by a handler. The Scheduler itself is a special Messenger transport that internally runs its own worker.

The key point: Symfony Scheduler is fully integrated into the Messenger. Schedule messages go through the same middleware pipeline as regular messages, can use the same retry system and end up in the same failure transport on error. That means existing monitoring tools, dashboards and alerting rules automatically apply to scheduled tasks as well. Developers do not need to build a separate system for cron monitoring, the Messenger ecosystem takes care of it.

<?php

declare(strict_types=1);

namespace App\Scheduler;

use App\Message\CleanupExpiredTokensMessage;
use App\Message\GenerateDailyReportMessage;
use App\Message\SyncProductCatalogMessage;
use Symfony\Component\Scheduler\Attribute\AsSchedule;
use Symfony\Component\Scheduler\RecurringMessage;
use Symfony\Component\Scheduler\Schedule;
use Symfony\Component\Scheduler\ScheduleProviderInterface;
use Symfony\Contracts\Cache\CacheInterface;

/**
 * Main application schedule, replaces all cron jobs with PHP-native configuration.
 * The #[AsSchedule] attribute registers this class as a Scheduler transport.
 */
#[AsSchedule('default')]
final class AppSchedule implements ScheduleProviderInterface
{
    public function __construct(
        private readonly CacheInterface $cache,
    ) {}

    public function getSchedule(): Schedule
    {
        return (new Schedule())
            // Run every 5 minutes via interval trigger
            ->add(RecurringMessage::every('5 minutes', new CleanupExpiredTokensMessage()))
            // Cron expression: every day at 03:00
            ->add(RecurringMessage::cron('0 3 * * *', new GenerateDailyReportMessage()))
            // Every hour with 300-second jitter to prevent thundering herd
            ->add(RecurringMessage::every('1 hour', new SyncProductCatalogMessage(), jitter: 300))
            // Use cache to persist schedule state across worker restarts
            ->stateful($this->cache);
    }
}

4. Triggers: cron, interval, jitter and custom

The Symfony Scheduler ships with several built-in trigger types. RecurringMessage::every() accepts a readable interval expression such as '5 minutes', '1 hour' or '30 seconds'. RecurringMessage::cron() takes a full cron expression and thereby supports any time specification, including weekdays and days of the month. For tasks where several workers would otherwise start the same task at the same time, the jitter parameter is essential: it adds a random delay and prevents the thundering herd problem, where many processes wake up simultaneously and overload the database.

For complex schedules that no standard trigger can express, you implement the TriggerInterface. A custom trigger defines the getNextRunDate() method, which computes the next date starting from the last execution time. That enables schedules such as "every last Friday of the month" or "only on business days between 08:00 and 18:00". The Symfony Scheduler calls getNextRunDate() again after every run, so the trigger can dynamically decide when the next execution is due.

5. Messages and handlers in the Scheduler context

Messages in Symfony Scheduler are normal Symfony Messenger message objects: plain PHP classes that carry data. They do not have to implement any interface and do not have to extend any base class. That makes it easy to reuse existing Messenger messages or to create new ones specifically for the Scheduler. The handler is likewise a normal Messenger handler: a class with the #[AsMessageHandler] attribute and an __invoke() method that takes the message class as a parameter.

An important detail: the handler runs in the context of the worker process, not in an HTTP request context. Doctrine's EntityManager, caches and other services are available, but HTTP-specific services such as RequestStack have no active request. That means handlers for the Symfony Scheduler should not process request data and do not need to return response objects. The handler performs the task, logs the result and returns nothing, or throws an exception if something goes wrong.

<?php

declare(strict_types=1);

namespace App\MessageHandler;

use App\Message\GenerateDailyReportMessage;
use App\Service\ReportGeneratorService;
use Doctrine\ORM\EntityManagerInterface;
use Psr\Log\LoggerInterface;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

/**
 * Handler for the daily report generation task scheduled via Symfony Scheduler.
 * Runs in worker context, no HTTP request available, full DI support.
 */
#[AsMessageHandler]
final readonly class GenerateDailyReportHandler
{
    public function __construct(
        private ReportGeneratorService $reportGenerator,
        private EntityManagerInterface $entityManager,
        private LoggerInterface $logger,
    ) {}

    /**
     * Generate the daily sales report and persist the result.
     */
    public function __invoke(GenerateDailyReportMessage $message): void
    {
        $this->logger->info('Starting daily report generation', [
            'triggered_at' => (new \DateTimeImmutable())->format(\DateTimeInterface::RFC3339),
        ]);

        try {
            $report = $this->reportGenerator->generateDailyReport(new \DateTimeImmutable('yesterday'));
            $this->entityManager->persist($report);
            $this->entityManager->flush();

            $this->logger->info('Daily report generated successfully', [
                'report_id' => $report->getId(),
                'row_count'  => $report->getRowCount(),
            ]);
        } catch (\Throwable $e) {
            // Throwing here triggers the Messenger retry mechanism
            $this->logger->error('Daily report generation failed', ['error' => $e->getMessage()]);
            throw $e;
        }
    }
}

6. Running the Scheduler worker

The Symfony Scheduler runs as a Messenger worker, started with the familiar command bin/console messenger:consume scheduler_default. The transport name corresponds to the name of the schedule from the #[AsSchedule] attribute, prefixed with scheduler_. In production environments this worker runs permanently under Supervisor, systemd or a container process manager. Unlike classic cron jobs, which start a new process on every run, the Scheduler worker is a long-lived process that internally checks the schedule and produces messages at the right time.

Restarting the worker on code changes matters: if the Schedule class is changed, the worker must be restarted for the new times to take effect. The --time-limit flag limits the worker's runtime and enables regular restarts. Combined with stateful($this->cache) in the Schedule class, the execution state survives worker restarts, the Scheduler knows which tasks have already run and does not accidentally skip them after a restart.

7. Error handling and retry strategies

When a Symfony Scheduler handler throws an exception, the Messenger's retry system kicks in. In config/packages/messenger.yaml you configure your own retry strategy for the Scheduler transport: number of attempts, delay between attempts and maximum wait time. Once retries are exhausted, the failed message ends up in the configured failure transport, typically a database table or a dedicated queue entry. From there it can be reprocessed manually or automatically.

For critical Scheduler tasks a differentiated strategy is recommended: light failures such as network timeouts are retried multiple times with exponential backoff, while severe failures such as a missing data structure go straight to the failure transport. The multiplier field in the retry configuration of Symfony Scheduler increases the wait time between each attempt. A monitoring tool such as Sentry catches the exceptions right at the first failure, before the retry system kicks in, so the team is informed before all retries are used up.

<?php
// config/packages/messenger.yaml, retry and failure transport for Symfony Scheduler

// framework:
//   messenger:
//     transports:
//       scheduler_default:
//         dsn: 'schedule://default'
//         retry_strategy:
//           max_retries: 3
//           delay: 1000        # 1 second initial delay
//           multiplier: 2      # exponential: 1s, 2s, 4s
//           max_delay: 30000   # max 30 seconds between retries
//
//       failed:
//         dsn: 'doctrine://default?queue_name=failed'
//         retry_strategy:
//           max_retries: 0     # no auto-retry from the failure transport
//
//     failure_transport: failed

// Routing, scheduler messages use the scheduler transport automatically
// All other messages can use a separate async transport:
// framework:
//   messenger:
//     routing:
//       'App\Message\GenerateDailyReportMessage': scheduler_default
//       'App\Message\SyncProductCatalogMessage': scheduler_default

// Start the Scheduler worker (keep alive with Supervisor/systemd):
// bin/console messenger:consume scheduler_default --time-limit=3600 -vv

8. Testing Scheduler tasks

One of the biggest advantages of Symfony Scheduler over classic cron jobs is testability. Since the schedule and the handler are normal PHP classes, they can be tested with PHPUnit. You test the handler like any other Messenger handler: with mocked dependencies and a concrete message instance. You test the schedule via the ScheduleTestCase base class from the Symfony Scheduler package, which provides methods to verify the next N execution times of a message.

Integration tests for the complete Symfony Scheduler flow use the InMemoryTransport: a message is queued in the Scheduler, the worker processes it synchronously, and the result is verified in the test. Symfony's KernelTestCase and the MessengerTestTrait, which provides assertions for sent messages and handler calls, help with this. This approach ensures that schedule, message and handler work together correctly, and does so before deployment to production.

9. Scheduler versus classic cron jobs compared

A direct comparison shows the concrete differences between classic cron jobs in the crontab and the Symfony Scheduler.

One downside of Symfony Scheduler compared to cron: it requires a permanently running worker process. Classic cron jobs are started by the operating system and need no background process. In environments without a process manager or container orchestration, that can be a hurdle. For most modern PHP projects that already run Messenger workers for asynchronous processing, however, this is no extra effort at all, the Scheduler uses the same infrastructure.

10. Summary

The Symfony Scheduler solves the fundamental problem of classic cron jobs: the separation of schedule and application code. With ScheduleProviderInterface and RecurringMessage, schedules become version-controlled PHP classes in the repository. Cron expressions, interval triggers and jitter configuration cover all common scenarios. Custom triggers allow arbitrarily complex schedules. Full Messenger integration brings automatic retry, failure handling and unified monitoring without extra effort.

The most important step for existing projects is the migration: create a message class and a handler for every cron entry, define the schedule in a Schedule class, set up the worker under Supervisor or systemd, and remove the old cron entry. The result is a system in which schedules go through the same review process as application code, and in which failures in scheduled tasks are immediately visible and handled automatically.

11. FAQ: Symfony Scheduler and Cron Jobs