Scheduler Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require bobrd/scheduler-bundle
   

   Add to config/app.php under providers:

   BobrD\SchedulerBundle\SchedulerBundle::class,
   

2. Publish Config (Optional)

   php artisan vendor:publish --provider="BobrD\SchedulerBundle\SchedulerBundle" --tag="config"
   

   Default config is minimal; check config/scheduler.php for tweaks.

3. Define a Job Create a command (e.g., php artisan make:command ProcessQueueJob). Annotate with @Schedule in the class or method:

   use BobrD\SchedulerBundle\Annotation\Schedule;
   
   class ProcessQueueJob extends Command
   {
       /**
        * @Schedule("0 * * * *") // Runs every minute
        */
       public function handle()
       {
           // Job logic
       }
   }
   

4. Run the Scheduler Add to app/Console/Kernel.php:

   protected function schedule(Schedule $schedule)
   {
       $schedule->command('process_queue_job')->everyMinute();
   }
   

   Start the scheduler in artisan schedule:run (or use a cron job):

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

Implementation Patterns

1. Job Definition Workflows

• Commands as Jobs: Convert existing commands into scheduled tasks by adding @Schedule or using Schedule::command().
• Closures for One-Off Tasks:

  $schedule->call(function () {
      // One-time logic
  })->at('03:00');
  

• Dynamic Scheduling: Use environment variables or config for flexibility:

  $schedule->command('backup_db')->hourlyAt(config('scheduler.backup_time'));
  

2. Integration with Laravel Ecosystem

• Queue Jobs: Chain scheduled commands with queue workers:

  $schedule->command('send_notifications')->daily()->withoutOverlapping();
  

• Event Listeners: Trigger events post-schedule execution:

  $schedule->command('generate_reports')->onOneServer()->then(function () {
      event(new ReportsGenerated());
  });
  

• Artisan Callbacks: Use before()/after() hooks:

  $schedule->command('cleanup_logs')
      ->daily()
      ->before(function () {
          Log::info('Starting cleanup...');
      });
  

3. Advanced Scheduling

• Timezones: Specify timezone-aware schedules:

  $schedule->command('sync_data')->timezone('America/New_York')->hourly();
  

• Randomized Delays: Avoid thundering herds:

  $schedule->command('fetch_feeds')->random(minute: 15);
  

• Conditional Execution: Skip if a condition fails:

  $schedule->command('process_invoices')->when(function () {
      return Invoice::pending()->exists();
  });
  

Gotchas and Tips

Pitfalls

1. Cron Syntax Confusion

   • The bundle uses Laravel’s Schedule facade (not raw cron). Avoid mixing * wildcards with Laravel’s helpers (e.g., everyMinute() vs. "* * * * *").
   • Fix: Stick to Laravel’s syntax (e.g., ->everyMinute()) unless you need cron-specific features.

2. Missing schedule:run

   • The scheduler won’t execute without artisan schedule:run. Test locally with:

     * * * * * cd /path && php artisan schedule:run >> /dev/null 2>&1
     

   • Tip: Use laravel-scheduler package for production monitoring.

3. Overlapping Jobs

   • Without withoutOverlapping(), jobs may pile up. Enable it for critical tasks:

     $schedule->command('long_running_task')->withoutOverlapping();
     

4. Environment-Specific Schedules

   • Schedules defined in Kernel.php run in all environments. Use when() or environment checks:

     if (app()->environment('production')) {
         $schedule->command('monitor_health')->everyFiveMinutes();
     }
     

Debugging

• Log Output: Redirect schedule:run to a log file:

  * * * * * cd /path && php artisan schedule:run >> /var/log/laravel_scheduler.log 2>&1
  

• Dry Runs: Test schedules without executing:

  php artisan schedule:list
  

• Manual Triggers: Force-run a command to debug:

  php artisan your:command
  

Extension Points

1. Custom Schedulers Override the default scheduler by binding your own Illuminate\Contracts\Schedule\Schedule in the container.

2. Annotation Parser Extend the @Schedule annotation logic by modifying the bundle’s AnnotationReader service.

3. Event Dispatching Listen for scheduling:running events to log or modify schedules dynamically:

   Event::listen('scheduling:running', function ($command) {
       Log::debug("Running scheduled command: {$command}");
   });
   

Pro Tips

• Use laravel-horizon: For queue-based scheduling, pair with Horizon for job monitoring.
• Database Backed Schedules: Store schedules in the DB for dynamic updates (requires spatie/laravel-schedule).
• Health Checks: Add a ping command to verify the scheduler is running:

  $schedule->command('ping')->everyFiveMinutes();