Beats Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require beats/beats-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Beats\BeatsBundle\BeatsBundle::class => ['all' => true],
   ];
   

2. First Use Case:

   • Register a beat (e.g., a cron-like task) via a service:

     # config/services.yaml
     services:
         App\Service\MyBeat:
             tags: ['beats.beat']
     

   • Implement Beats\BeatsBundle\Beat\BeatInterface in your service:

     use Beats\BeatsBundle\Beat\BeatInterface;
     
     class MyBeat implements BeatInterface {
         public function run() {
             // Your logic here
         }
     }
     

   • Configure the beat in config/beats.yaml:

     beats:
         my_beat:
             class: App\Service\MyBeat
             schedule: "*/5 * * * *"  # Cron syntax
     

3. Trigger Manually (for testing):

   php bin/console beats:run my_beat
   

Implementation Patterns

Core Workflows

1. Scheduling Beats:

   • Use cron syntax (@hourly, */10 * * * *, etc.) in beats.yaml.
   • Example: Run a beat every Monday at 3 AM:

     beats:
         weekly_report:
             class: App\Service\WeeklyReportBeat
             schedule: "0 3 * * 1"
     

2. Dependency Injection:

   • Inject services into beats via constructor (standard Symfony DI):

     class MyBeat implements BeatInterface {
         private $logger;
     
         public function __construct(LoggerInterface $logger) {
             $this->logger = $logger;
         }
     
         public function run() {
             $this->logger->info('Beat running!');
         }
     }
     

3. Event-Driven Triggers:

   • Use Beats\BeatsBundle\Event\BeatEvent to dispatch events before/after execution:

     use Beats\BeatsBundle\Event\BeatEvent;
     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class MyBeatSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 'beats.my_beat.pre_run' => 'onPreRun',
                 'beats.my_beat.post_run' => 'onPostRun',
             ];
         }
     }
     

4. Command-Line Integration:

   • Run all beats manually:

     php bin/console beats:run all
     

   • List registered beats:

     php bin/console beats:list
     

5. Logging and Output:

   • Log beat execution via Symfony’s logger or output directly:

     public function run() {
         echo "Running beat at " . date('Y-m-d H:i:s') . "\n";
     }
     

Gotchas and Tips

Pitfalls

1. Outdated Package:

   • Last release in 2014—expect compatibility issues with modern Symfony/Laravel (if used in Laravel via Symfony bridge).
   • Workaround: Fork and update dependencies (e.g., symfony/dependency-injection, symfony/console).

2. No Built-in Persistence:

   • Beats run in-memory; no tracking of missed executions or history.
   • Tip: Log execution timestamps to a database or file for auditing.

3. Cron Syntax Only:

   • No support for advanced scheduling (e.g., "run every 3 hours, but not between 2–5 AM").
   • Workaround: Use a wrapper service to parse custom logic.

4. No Retry Mechanism:

   • Failed beats terminate silently. Add retry logic manually:

     public function run() {
         try {
             // Risky operation
         } catch (Exception $e) {
             // Log and retry (e.g., via Symfony Messenger)
         }
     }
     

5. Laravel Integration Quirks:

   • If using in Laravel, manually bind the bundle to the container:

     $app->register(new Beats\BeatsBundle\BeatsBundle());
     

   • Tip: Use symfony/console bridge for command-line access.

Debugging Tips

1. Enable Verbose Output:

   php bin/console beats:run my_beat -v
   

2. Check Configuration:

   • Validate beats.yaml syntax (YAML errors may silently fail).
   • Use php bin/console debug:config beats to inspect loaded beats.

3. Test Locally:

   • Mock the scheduler to test beats without waiting:

     // In tests, inject a mock BeatManager
     $beatManager = $this->createMock(BeatManager::class);
     $beatManager->expects($this->once())->method('runBeat')->with('my_beat');
     

Extension Points

1. Custom Schedulers:

   • Override Beats\BeatsBundle\Scheduler\SchedulerInterface for non-cron logic (e.g., event-based triggers).

2. Beat Metadata:

   • Add custom metadata to beats via setMetadata() in BeatInterface:

     public function setMetadata(array $metadata) {}
     

   • Useful for tracking dependencies or configuration.

3. Environment-Specific Beats:

   • Load different beats.yaml per environment (e.g., beats.dev.yaml, beats.prod.yaml) via Symfony’s parameter system.

4. Performance Optimization:

   • For long-running beats, use Symfony’s Process component to run them asynchronously:

     use Symfony\Component\Process\Process;
     
     public function run() {
         $process = new Process(['php', 'script.php']);
         $process->start();
     }