Cron Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require shapecode/cron-bundle
   

   Add to config/app.php under providers:

   ShapeCode\CronBundle\CronBundle::class,
   

   Publish the config (optional):

   php artisan vendor:publish --provider="ShapeCode\CronBundle\CronBundle" --tag="config"
   

2. Basic Registration Define a command (e.g., app/Console/Commands/ExampleCommand.php):

   namespace App\Console\Commands;
   
   use Illuminate\Console\Command;
   
   class ExampleCommand extends Command
   {
       protected $signature = 'example:task';
       protected $description = 'An example scheduled task';
   }
   

   Register it in config/cron.php:

   'commands' => [
       'App\Console\Commands\ExampleCommand' => '*/5 * * * *', // Every 5 minutes
   ],
   

3. First Run

   php artisan cron:run
   

   Or use a system cron job:

   * * * * * cd /path-to-project && php artisan cron:run >> /dev/null 2>&1
   

Implementation Patterns

1. Command Registration

• Dynamic Registration: Register commands programmatically in a service provider:

  public function boot()
  {
      $this->app->make('ShapeCode\CronBundle\CronManager')->addCommand(
          \App\Console\Commands\ExampleCommand::class,
          '*/10 * * * *' // Every 10 minutes
      );
  }
  

• Environment-Specific Scheduling: Use config overrides:

  // config/cron.php (production)
  'commands' => [
      'App\Console\Commands\HeavyTask' => '0 3 * * *' // Nightly
  ],
  

2. Logging and Monitoring

• Log Output: Redirect cron logs to a file:

  php artisan cron:run >> storage/logs/cron.log 2>&1
  

• Custom Logging: Extend the CronManager to log missed jobs:

  $manager->setLogger(new \Monolog\Logger('cron'));
  

3. Integration with Laravel Jobs

• Queueable Commands: Convert commands to queueable jobs:

  class ExampleCommand extends Command
  {
      public function handle()
      {
          dispatch(new \App\Jobs\ProcessData);
      }
  }
  

4. Timezone Handling

• Set the default timezone in config/cron.php:

  'timezone' => 'America/New_York',
  

5. Testing

• Mock Cron Runs: Use CronManager in tests:

  $manager = $this->app->make('ShapeCode\CronBundle\CronManager');
  $manager->run(); // Simulate cron execution
  

Gotchas and Tips

Pitfalls

• Missing System Cron Job: Forgetting to set up the system cron job (php artisan cron:run) will prevent tasks from running.
• Overlapping Executions: Commands with short intervals (e.g., * * * * *) may run concurrently if not idempotent.
• Timezone Mismatch: Cron expressions use the system timezone by default; explicitly set timezone in config to avoid surprises.

Debugging

• Check Last Run: Inspect storage/logs/cron.log for errors.
• Dry Run: Test schedules with php artisan cron:run --dry-run (if supported).
• Artisan Command: Use php artisan cron:list to verify registered commands.

Extension Points

• Custom Schedules: Extend ShapeCode\CronBundle\Schedule\Schedule to add custom syntax (e.g., "every 2 hours").
• Pre/Post Hooks: Override CronManager to add logic before/after command execution:

  $manager->beforeRun(function () {
      Log::info('Cron jobs starting...');
  });
  

Performance Tips

• Batch Commands: Group related commands into a single cron job for efficiency.
• Lazy Loading: Use lazy option in config to defer command loading:

  'commands' => [
      'App\Console\Commands\LazyCommand' => [
          'schedule' => '* * * * *',
          'lazy' => true,
      ],
  ],
  

Security

• Restrict Artisan Access: Ensure php artisan cron:run is only executable by trusted users.
• Environment Checks: Validate environment in commands:

  if (app()->environment('local')) {
      $this->info('Skipping in local environment.');
      return;
  }