Cron Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require aldaflux/cron-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       Aldaflux\CronBundle\AldafluxCronBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Publish the default config:

   php bin/console aldacron:install
   

   Edit config/packages/aldaflux_cron.yaml to define your first cron job:

   aldacron:
       jobs:
           my_first_job:
               command: "app:my-command"
               schedule: "*/5 * * * *"  # Every 5 minutes
   

3. First Use Case Create a console command (e.g., app:my-command) to test:

   php bin/console make:command MyCommand
   

   Run the job manually to verify:

   php bin/console aldacron:run my_first_job
   

Implementation Patterns

Workflow Integration

1. Job Definition Define jobs in config/packages/aldaflux_cron.yaml:

   aldacron:
       jobs:
           sync_users:
               command: "app:sync-users"
               schedule: "0 * * * *"  # Hourly
               timeout: 3600          # 1 hour timeout
               environment:           # Optional env vars
                   SYNC_MODE: "full"
   

2. Dynamic Job Loading Use the AldafluxCronBundle\EventListener\JobLoaderListener to load jobs from a database or API:

   // src/EventListener/CustomJobLoader.php
   use Aldaflux\CronBundle\Event\JobLoadEvent;
   
   class CustomJobLoader implements EventSubscriber
   {
       public static function getSubscribedEvents()
       {
           return [
               JobLoadEvent::class => 'loadJobs',
           ];
       }
   
       public function loadJobs(JobLoadEvent $event)
       {
           $jobs = $this->fetchJobsFromDatabase();
           $event->addJobs($jobs);
       }
   }
   

3. Logging and Monitoring Enable logging in config/packages/aldaflux_cron.yaml:

   aldacron:
       logging: true
       log_file: "%kernel.logs_dir%/aldacron.log"
   

   Check logs with:

   tail -f var/log/aldacron.log
   

4. Environment-Specific Scheduling Use Symfony’s environment-aware config (e.g., config/packages/aldaflux_cron/{env}.yaml) to toggle jobs:

   # config/packages/aldaflux_cron/dev.yaml
   aldacron:
       jobs:
           debug_job:
               command: "app:debug"
               schedule: "* * * * *"  # Only in dev
   

Gotchas and Tips

Common Pitfalls

1. Cron Syntax Errors

   • Validate schedules using crontab.guru. Example:

     schedule: "0 0 * * *"  # Daily at midnight (correct)
     schedule: "0 0 * * 0"  # Weekly on Sunday (correct)
     schedule: "*/5 * * * *" # Every 5 minutes (correct)
     

   • Avoid invalid syntax like 0 0 * * (missing day of week).

2. Command Not Found

   • Ensure the command class exists and is autoloaded. Test manually:

     php bin/console app:my-command
     

   • Check for typos in the command key (case-sensitive).

3. Permission Issues

   • Ensure the web server user (e.g., www-data) has read/write access to:
     • var/log/aldacron.log (if logging is enabled).
     • The Symfony bin/console file (chmod 755).

4. Time Zone Mismatches

   • CronBundle uses the system time zone. Set it explicitly in config/packages/aldaflux_cron.yaml:

     aldacron:
         timezone: "Europe/Paris"
     

Debugging Tips

1. Dry Run Mode Test schedules without executing commands:

   php bin/console aldacron:run --dry-run
   

2. Manual Job Execution Run a specific job on demand:

   php bin/console aldacron:run job_name
   

3. Event Listeners Subscribe to events for custom logic:

   use Aldaflux\CronBundle\Event\JobEvent;
   
   class MySubscriber implements EventSubscriber
   {
       public static function getSubscribedEvents()
       {
           return [
               JobEvent::PRE_EXECUTE => 'onPreExecute',
               JobEvent::POST_EXECUTE => 'onPostExecute',
           ];
       }
   
       public function onPreExecute(JobEvent $event)
       {
           if ($event->getJob()->getName() === 'sync_users') {
               $event->setEnvironment(['DRY_RUN' => true]);
           }
       }
   }
   

Extension Points

1. Custom Job Storage Override the default job storage (e.g., database) by implementing Aldaflux\CronBundle\Storage\JobStorageInterface:

   class DatabaseJobStorage implements JobStorageInterface
   {
       public function load(): array
       {
           return $this->fetchFromDatabase();
       }
   
       public function save(array $jobs): void
       {
           $this->persistToDatabase($jobs);
       }
   }
   

   Register it in services.yaml:

   services:
       Aldaflux\CronBundle\Storage\JobStorageInterface: '@database_job_storage'
   

2. Hooks for Pre/Post Execution Use the JobEvent to modify behavior:

   $event->setCommand('app:new-command'); // Override command
   $event->setEnvironment(['KEY' => 'value']); // Add env vars
   $event->stopPropagation(); // Skip execution
   

3. Conditional Job Execution Dynamically enable/disable jobs based on logic:

   use Aldaflux\CronBundle\Event\JobLoadEvent;
   
   $event->addJob('conditional_job', [
       'command' => 'app:conditional',
       'schedule' => '* * * * *',
       'enabled' => $this->shouldJobRun(), // Custom logic
   ]);