Cron Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require beyondbluesky/cron-manager-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       BeyondBluesky\CronManagerBundle\BeyondBlueskyCronManagerBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define cron jobs in config/packages/beyondbluesky_cron_manager.yaml:

   cron_manager:
       jobs:
           my_job:
               command: 'app:my-command'
               schedule: '*/5 * * * *'  # Every 5 minutes
               user: 'www-data'
               enabled: true
   

3. First Use Case Create a Symfony command (e.g., app:my-command) to execute your task. The bundle will handle scheduling via cron.

Implementation Patterns

Workflows

1. Job Definition

   • Define jobs in YAML with:
     • command: Symfony command to execute.
     • schedule: Cron expression (e.g., 0 0 * * * for daily).
     • user: User to run the command (optional).
     • enabled: Toggle job activation (default: true).
   • Example:

     cron_manager:
         jobs:
             cleanup_db:
                 command: 'app:cleanup-db'
                 schedule: '0 3 * * *'  # Daily at 3 AM
                 user: 'root'
     

2. Dynamic Job Management

   • Use the CronManager service to enable/disable jobs programmatically:

     use BeyondBluesky\CronManagerBundle\Service\CronManager;
     
     public function __construct(private CronManager $cronManager) {}
     
     public function toggleJob(string $jobName, bool $enabled) {
         $this->cronManager->setJobEnabled($jobName, $enabled);
     }
     

3. Logging and Monitoring

   • Log cron job executions in your command class:

     use Psr\Log\LoggerInterface;
     
     public function execute(InputInterface $input, OutputInterface $output, LoggerInterface $logger) {
         $logger->info('Job executed at ' . new \DateTime());
         // Job logic here
     }
     

4. Environment-Specific Schedules

   • Use Symfony’s parameter system to override schedules per environment:

     # config/packages/dev/beyondbluesky_cron_manager.yaml
     cron_manager:
         jobs:
             my_job:
                 schedule: '*/1 * * * *'  # More frequent in dev
     

Integration Tips

• Symfony Console Integration: Ensure your commands are autowired and use Symfony’s Command trait.
• Dependency Injection: Inject CronManager into controllers/services to manage jobs dynamically.
• Testing: Mock CronManager in tests to verify job toggling logic.

Gotchas and Tips

Pitfalls

1. Cron Syntax Errors

   • Invalid cron expressions (e.g., */9 * * * *) will fail silently. Validate expressions using tools like crontab.guru.
   • Fix: Test schedules locally with echo commands before deploying.

2. User Permissions

   • If the user field is misconfigured, cron jobs may fail due to permission issues.
   • Fix: Ensure the specified user has access to the command’s dependencies (e.g., database, files).

3. Bundle Not Auto-Registering

   • If jobs aren’t picked up, verify the bundle is enabled in config/bundles.php and the YAML file is correctly named/located.
   • Fix: Clear cache after installation:

     php bin/console cache:clear
     

4. Command Not Found

   • If the command field references a non-existent Symfony command, the job will fail.
   • Fix: Double-check the command name (e.g., app:my-command vs. my:command).

Debugging

• Check Cron Logs: Tail the system cron logs (/var/log/syslog or journalctl -u cron) for execution errors.
• Dry Run: Temporarily replace the command with echo to verify scheduling:

  cron_manager:
      jobs:
          test_job:
              command: 'echo "Testing cron at $(date)"'
              schedule: '* * * * *'
  

Extension Points

1. Custom Job Storage

   • Override job storage by implementing BeyondBluesky\CronManagerBundle\Storage\JobStorageInterface and configuring it in services.yaml:

     services:
         BeyondBluesky\CronManagerBundle\Service\CronManager:
             arguments:
                 $jobStorage: '@app.custom_job_storage'
     

2. Event Listeners

   • Listen for job execution events (e.g., before/after) by implementing BeyondBluesky\CronManagerBundle\Event\CronJobEvent and tagging the service:

     services:
         App\EventListener\CronJobListener:
             tags:
                 - { name: 'beyondbluesky.cron_manager.event_listener' }
     

3. Dynamic Schedules

   • Fetch schedules from a database or API by extending the JobLoader service:

     use BeyondBluesky\CronManagerBundle\Loader\JobLoaderInterface;
     
     class DatabaseJobLoader implements JobLoaderInterface {
         public function load(): array {
             return $this->fetchJobsFromDatabase();
         }
     }
     

Tips

• Idempotency: Design commands to be idempotent (safe to rerun) to handle missed cron executions.
• Environment Awareness: Use %kernel.environment% in YAML to conditionally define jobs:

  cron_manager:
      jobs:
          prod_only_job:
              command: 'app:prod-task'
              schedule: '0 0 * * *'
              enabled: '%kernel.environment% === "prod"'
  

• Backup Jobs: Schedule backup jobs with nice or ionice to reduce system impact:

  cron_manager:
      jobs:
          backup_db:
              command: 'nice -n 19 app:backup-db'
              schedule: '0 2 * * *'