Cron Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require colourstream/cron-bundle:dev-master and update dependencies. Register the bundle in config/bundles.php (Symfony 3+) or ApplicationKernel.php (Symfony 2.x):

   ColourStream\Bundle\CronBundle\ColourStreamCronBundle::class => ['all' => true],
   

2. Database Setup Update your schema:

   php bin/console doctrine:schema:update --force
   

   This creates the cron_job table to store scheduled tasks.

3. First Use Case: Register a Job Define a command (e.g., app/Command/ExampleCommand.php):

   namespace App\Command;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class ExampleCommand extends Command
   {
       protected function configure()
       {
           $this->setName('app:example');
       }
   
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $output->writeln('Running example job!');
       }
   }
   

   Register it via YAML (config/packages/cron.yaml):

   colourstream_cron:
       jobs:
           app_example:
               command: 'app:example'
               schedule: '0 0 * * *'  # Runs daily at midnight
   

4. Trigger Jobs Scan for new jobs:

   php bin/console cron:scan
   

   Run pending jobs:

   php bin/console cron:run
   

Implementation Patterns

Workflows

1. Job Registration

   • YAML/Config: Define jobs in config/packages/cron.yaml under colourstream_cron.jobs.

     colourstream_cron:
         jobs:
             cleanup_cache:
                 command: 'cache:clear'
                 schedule: '0 3 * * *'  # Daily at 3 AM
                 description: 'Clear cache nightly'
     

   • Dynamic Registration: Use the CronManager service to register jobs programmatically:

     $manager = $container->get('colourstream_cron.manager');
     $manager->addJob('dynamic_job', 'app:dynamic', '0 0 * * *');
     

2. Running Jobs

   • Manual Trigger: Use cron:run to execute pending jobs.
   • Webhook Integration: For hosted environments, expose an endpoint (e.g., via Symfony’s Router) to trigger jobs via HTTP:

     // src/Controller/CronController.php
     use Symfony\Component\HttpFoundation\Response;
     use Symfony\Component\Routing\Annotation\Route;
     
     class CronController
     {
         #[Route('/cron/run', name: 'cron_run')]
         public function run(CronManager $manager): Response
         {
             $manager->runJobs();
             return new Response('Jobs executed');
         }
     }
     

     Configure a webcron service (e.g., Cron-job.org) to hit this endpoint.

3. Logging and Monitoring

   • Use Symfony’s Logger to log job execution:

     use Psr\Log\LoggerInterface;
     
     class ExampleCommand extends Command
     {
         private $logger;
     
         public function __construct(LoggerInterface $logger)
         {
             $this->logger = $logger;
         }
     
         protected function execute(InputInterface $input, OutputInterface $output)
         {
             $this->logger->info('Example job started');
             // ...
         }
     }
     

   • Query the cron_job table for execution history:

     php bin/console doctrine:query:sql "SELECT * FROM cron_job WHERE command = 'app:example'"
     

4. Environment-Specific Scheduling Use Symfony’s environment variables or parameter bags to toggle jobs:

   # config/packages/dev/cron.yaml
   colourstream_cron:
       jobs:
           debug_logs:
               command: 'app:debug-logs'
               schedule: '*/5 * * * *'  # Every 5 minutes (dev only)
   

Gotchas and Tips

Pitfalls

1. Database Schema Mismatch

   • If you modify the cron_job table (e.g., adding columns), run doctrine:schema:update before registering new jobs. Migrations are not handled automatically.
   • Fix: Backup your database before schema updates.

2. Job Overlaps

   • The bundle does not prevent overlapping executions if the job’s runtime exceeds its scheduled interval (e.g., a job set to run every 5 minutes but takes 10 minutes to complete).
   • Fix: Implement a lock mechanism in your command or use Symfony’s Process to kill stale jobs:

     use Symfony\Component\Process\Process;
     
     $process = new Process(['php', 'bin/console', 'app:example']);
     $process->start();
     if (!$process->isRunning()) {
         $this->logger->warning('Job already running, skipping');
         return;
     }
     

3. Cron Syntax Errors

   • Invalid schedules (e.g., 0 0 * * missing a field) will silently fail during cron:scan.
   • Fix: Validate schedules using a library like cron-expression or add a custom validator:

     use Cron\CronExpression;
     
     public function isValidSchedule(string $schedule): bool
     {
         try {
             new CronExpression($schedule);
             return true;
         } catch (\Exception $e) {
             return false;
         }
     }
     

4. Symfony 2.x Limitations

   • The bundle is untested on Symfony 3+. Assumptions about service containers (e.g., autowiring) may break.
   • Fix: Use dependency injection manually or fork the bundle for Symfony 4+ compatibility.

Tips

1. Idempotency Design commands to be idempotent (safe to rerun). Example:

   // app/Command/SendReportCommand.php
   protected function execute(InputInterface $input, OutputInterface $output)
   {
       $report = $this->reportRepository->findOneBy(['sent_at' => null]);
       if (!$report) {
           $output->writeln('No unsent reports found');
           return;
       }
       // Send report logic...
   }
   

2. Environment-Aware Scheduling Use %kernel.environment% in schedules to disable jobs in production:

   colourstream_cron:
       jobs:
           dev_only_job:
               command: 'app:dev-task'
               schedule: '%kernel.environment% == "dev" ? "*/1 * * * *" : ""'
   

3. Custom Job Metadata Extend the cron_job table to store additional fields (e.g., priority, timeout):

   php bin/console make:migration
   

   Update the bundle’s CronJob entity or create a custom repository.

4. Testing Jobs Mock the CronManager in PHPUnit tests:

   use ColourStream\Bundle\CronBundle\Manager\CronManager;
   
   $cronManager = $this->createMock(CronManager::class);
   $cronManager->expects($this->once())
               ->method('runJobs')
               ->willReturn(true);
   $this->container->set('colourstream_cron.manager', $cronManager);
   

5. Performance For large-scale applications, batch jobs by priority or use a queue system (e.g., Symfony Messenger) to avoid long-running cron:run processes.

   • Example: Split jobs into "high", "medium", and "low" priority tables and run them sequentially.

6. Webhook Security If exposing a web endpoint for cron:run, add authentication:

   #[Route('/cron/run', name: 'cron_run', methods: ['POST'])]
   public function run(CronManager $manager, Request $request): Response
   {
       if (!$request->headers->get('X-Cron-Secret') === $this->getParameter('cron_secret')) {
           throw $this->createAccessDeniedException();
       }
       $manager->runJobs();
       return new Response('OK');
   }