Scheduler Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require caeligo/scheduler-bundle
   

   Register the bundle in config/bundles.php:

   return [
       // ...
       Caeligo\SchedulerBundle\CaeligoSchedulerBundle::class => ['all' => true],
   ];
   

2. Publish Configuration & Assets

   php bin/console caeligo:scheduler:install
   

   This generates:

   • config/packages/caeligo_scheduler.yaml (default config)
   • var/log/scheduler/ (log directory)
   • public/scheduler/ (dashboard assets)

3. Define Your First Task Use the #[AsSchedulableCommand] attribute on a Symfony command:

   use Caeligo\SchedulerBundle\Attribute\AsSchedulableCommand;
   
   #[AsSchedulableCommand(
       name: 'app:example-task',
       schedule: '@hourly', // or '0 * * * *' for cron
       description: 'Runs hourly'
   )]
   class ExampleTask extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output): int
       {
           $output->writeln('Task executed!');
           return Command::SUCCESS;
       }
   }
   

4. Install the Crontab Entry

   php bin/console caeligo:scheduler:install:cron
   

   Or via the dashboard at /scheduler.

First Use Case: Running a Scheduled Command

• Trigger Manually (for testing):

  php bin/console caeligo:scheduler:run app:example-task
  

• View Logs:

  php bin/console caeligo:scheduler:logs app:example-task
  

• Check Status:

  php bin/console caeligo:scheduler:list
  

Implementation Patterns

Workflow: Developing Scheduled Tasks

1. Attribute-Based Definition Use #[AsSchedulableCommand] on existing Symfony commands. No need to duplicate logic or create separate entities.

   #[AsSchedulableCommand(
       schedule: '0 3 * * *', // Runs daily at 3 AM
       overlap: 'skip',       // Skip if previous run is still active
       timeout: 300           // Max execution time (seconds)
   )]
   

2. Configuration Overrides Override default settings in config/packages/caeligo_scheduler.yaml:

   caeligo_scheduler:
       log_directory: '%kernel.project_dir%/var/log/custom_scheduler'
       default_timezone: 'Europe/Berlin'
       roles:
           scheduler_dashboard: ROLE_ADMIN
   

3. Dynamic Scheduling Use PHP logic to conditionally enable/disable tasks:

   #[AsSchedulableCommand(
       schedule: '@daily',
       enabled: false // Disable by default
   )]
   class ConditionalTask extends Command
   {
       public function __construct(private bool $isEnabled) {}
   
       protected function configure(): void
       {
           $this->setEnabled($this->isEnabled);
       }
   }
   

Integration Tips

• Shared Hosting Compatibility Use the HTTP trigger fallback for environments without cron:

  caeligo_scheduler:
      http_trigger:
          enabled: true
          endpoint: '/scheduler/webhook'
  

  Then call https://your-site.com/scheduler/webhook via a third-party service (e.g., Pinger, Cron-job.org).

• Logging and Monitoring Integrate with Monolog handlers for centralized logging:

  monolog:
      handlers:
          scheduler:
              type: stream
              path: '%kernel.logs_dir%/scheduler.log'
              level: debug
  

• Testing Mock the scheduler in PHPUnit:

  use Caeligo\SchedulerBundle\Scheduler\SchedulerInterface;
  
  $scheduler = $this->createMock(SchedulerInterface::class);
  $scheduler->method('runTask')->willReturn(true);
  $this->container->set(SchedulerInterface::class, $scheduler);
  

Gotchas and Tips

Pitfalls

1. Crontab Permission Issues

   • Ensure the cron user (often www-data or root) has write access to:
     • var/log/scheduler/
     • The Symfony cache/ and var/ directories.
   • Fix with:

     chown -R www-data:www-data var/
     chmod -R 775 var/
     

2. Timezone Mismatches

   • The scheduler uses the system timezone by default. Explicitly set it in config:

     caeligo_scheduler:
         default_timezone: 'America/New_York'
     

   • Verify with:

     php bin/console debug:config caeligo_scheduler
     

3. Overlap Handling

   • Default behavior ('skip') may hide failures. Use 'fail' to throw exceptions:

     #[AsSchedulableCommand(overlap: 'fail')]
     

   • Check overlap status via:

     php bin/console caeligo:scheduler:status app:example-task
     

4. Dashboard Caching

   • The Twig dashboard caches routes. Clear cache after config changes:

     php bin/console cache:clear
     

Debugging Tips

• Enable Verbose Logging Add to config/packages/monolog.yaml:

  handlers:
      scheduler:
          type: stream
          path: '%kernel.logs_dir%/scheduler.log'
          level: debug
          channels: ['!event']
  

• Check Crontab Installation Verify the cron entry exists:

  crontab -l | grep caeligo
  

  Reinstall if missing:

  php bin/console caeligo:scheduler:install:cron
  

• Task Execution Debugging Use Symfony’s debug toolbar to inspect:

  • HTTP triggers (if enabled).
  • Command execution context.

Extension Points

1. Custom Task Storage Override the file-based storage by implementing Caeligo\SchedulerBundle\Storage\TaskStorageInterface:

   use Caeligo\SchedulerBundle\Storage\TaskStorageInterface;
   
   class DatabaseTaskStorage implements TaskStorageInterface
   {
       public function saveTask(Task $task): void { /* ... */ }
       public function findTask(string $name): ?Task { /* ... */ }
       // ...
   }
   

   Register as a service:

   services:
       Caeligo\SchedulerBundle\Storage\TaskStorageInterface: '@database_task_storage'
   

2. Event Listeners Subscribe to scheduler events (e.g., TaskRunningEvent):

   use Caeligo\SchedulerBundle\Event\TaskRunningEvent;
   use Symfony\Component\EventDispatcher\EventSubscriberInterface;
   
   class SchedulerSubscriber implements EventSubscriberInterface
   {
       public static function getSubscribedEvents(): array
       {
           return [
               TaskRunningEvent::NAME => 'onTaskRunning',
           ];
       }
   
       public function onTaskRunning(TaskRunningEvent $event): void
       {
           // Log or notify before task execution
       }
   }
   

3. Custom Dashboard Templates Override Twig templates in templates/bundles/caeligo_scheduler/:

   mkdir -p templates/bundles/caeligo_scheduler/
   cp vendor/caeligo/scheduler-bundle/Resources/views/* templates/bundles/caeligo_scheduler/
   

   Extend the base template (index.html.twig) to add custom fields.