Cron Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require amadeus-m/cron-bundle
   

   Add to config/bundles.php (Symfony 4+):

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

2. Database Setup:

   php bin/console make:migration
   php bin/console doctrine:migrations:migrate
   

3. First Job Creation:

   php bin/console cron:create
   

   Follow prompts to define a job (e.g., send_daily_emails). Example YAML config (config/cron.yml):

   cron:
       jobs:
           send_daily_emails:
               command: 'app:send-emails'
               schedule: '0 0 * * *'
               enabled: true
   

4. Run Manually:

   php bin/console cron:run send_daily_emails
   

Implementation Patterns

Workflows

1. Job Definition:

   • Use cron:create interactively or define jobs in config/cron.yml:

     cron:
         jobs:
             cleanup_logs:
                 command: 'app:cleanup-logs'
                 schedule: '0 0 * * 0'  # Weekly on Sunday
                 enabled: false
                 timeout: 3600
     

   • Commands: Reference Symfony console commands (e.g., app:generate-reports).

2. Scheduling:

   • Leverage cron syntax (* * * * *) or use AmadeusM\CronBundle\Job\JobInterface for custom logic.
   • Example: Run a job every 5 minutes:

     sync_data:
         command: 'app:sync-data'
         schedule: '*\/5 * * * *'
     

3. Integration with Symfony Services:

   • Inject services into jobs via dependency injection. Create a custom job class:

     // src/Command/CustomJobCommand.php
     namespace App\Command;
     use AmadeusM\CronBundle\Job\JobInterface;
     use Symfony\Component\Console\Command\Command;
     use Symfony\Component\DependencyInjection\ContainerInterface;
     
     class CustomJobCommand extends Command implements JobInterface {
         private $container;
         public function __construct(ContainerInterface $container) {
             $this->container = $container;
             parent::__construct();
         }
         public function run() {
             $this->container->get('app.service')->execute();
         }
     }
     

   • Register the job in config/cron.yml:

     custom_job:
         class: App\Command\CustomJobCommand
         schedule: '0 * * * *'
     

4. Logging and Monitoring:

   • Use Symfony’s monolog for job logs. Example in config/packages/monolog.yaml:

     handlers:
         cron:
             type: stream
             path: "%kernel.logs_dir%/%kernel.environment%.cron.log"
             level: debug
     

   • Check job status with:

     php bin/console cron:list
     

5. Background Execution:

   • Start the daemon (useful for Heroku/non-cron environments):

     php bin/console cron:start --blocking  # Foreground (debugging)
     php bin/console cron:start            # Background (production)
     

   • Stop the daemon:

     php bin/console cron:stop
     

Gotchas and Tips

Pitfalls

1. Database Schema Mismatch:

   • After updating the bundle, run php bin/console make:migration and php bin/console doctrine:migrations:migrate to avoid Job table errors.

2. Cron Syntax Errors:

   • Invalid schedules (e.g., * * * *) will silently fail. Validate with:

     php bin/console cron:list
     

   • Use crontab.guru to test schedules.

3. Permission Issues:

   • Ensure the cron user (or web server user) has write access to:
     • var/log/ (for logs).
     • var/cache/ (for job locks).
   • Fix with:

     chmod -R 775 var/
     

4. Job Locking:

   • The bundle uses file-based locks (var/cron/locks/). Delete stale locks if jobs hang:

     rm -f var/cron/locks/*
     

5. Timezone Misalignment:

   • Jobs run in the server’s timezone. Force UTC in config/packages/framework.yaml:

     timezone: UTC
     

Debugging

1. Dry Runs:

   • Test jobs manually before scheduling:

     php bin/console cron:run job_name --force
     

2. Verbose Output:

   • Enable debug mode for detailed logs:

     php bin/console cron:run --env=dev job_name
     

3. Job History:

   • Query the cron_job table directly for execution logs:

     SELECT * FROM cron_job WHERE name = 'job_name' ORDER BY created_at DESC;
     

Tips

1. Environment-Specific Jobs:

   • Disable jobs in production if needed:

     # config/cron/prod.yml
     cron:
         jobs:
             debug_job:
                 enabled: false
     

2. Custom Job Classes:

   • Extend AmadeusM\CronBundle\Job\JobInterface for reusable logic:

     class BaseJob implements JobInterface {
         public function run() {
             // Shared setup/teardown
         }
     }
     

3. Heroku/Platform-as-a-Service:

   • Use cron:start --blocking in a web dyno (not recommended for production; prefer add-ons like Heroku Scheduler).

4. Testing:

   • Mock the cron bundle in PHPUnit:

     $this->container->get('cron.manager')->runJob('test_job');
     

   • Use cron:run in tests with --env=test.

5. Extending the Bundle:

   • Override the JobManager service to add pre/post hooks:

     # config/services.yaml
     AmadeusM\CronBundle\Job\JobManager:
         arguments:
             $logger: '@monolog.logger.cron'
             $preRunHooks: ['@app.cron.pre_hook']