Illuminate Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer:

   composer require culabs/illuminate-bundle:dev-master
   

   Update dependencies:

   composer update --prefer-dist
   

2. Register the Bundle Add to app/AppKernel.php:

   public function registerBundles()
   {
       return [
           // ...
           new CULabs\IlluminateBundle\CULabsIlluminateBundle(),
       ];
   }
   

3. Configure Laravel Components Define Laravel-specific settings in config.yml:

   cu_labs_illuminate:
       app:
           key: 'your-32-char-app-key'  # Laravel app key
       database:
           connections:
               mysql:
                   database: '%database_name%'
                   username: '%database_user%'
                   password: '%database_password%'
       queue:
           default: redis  # e.g., 'database', 'redis', 'beanstalkd'
   

4. First Use Case: Dispatch a Job Create a Laravel-style job (e.g., SendReminderEmail) and dispatch it:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class SomeController
   {
       private $dispatcher;
   
       public function __construct(ContainerInterface $container)
       {
           $this->dispatcher = $container->get('bus_dispatcher');
       }
   
       public function sendReminder()
       {
           $job = new SendReminderEmail();
           $job->delay(2);  // Delay in seconds
           $this->dispatcher->dispatch($job);
       }
   }
   

Implementation Patterns

Queue Workflows

1. Job Creation Extend Laravel’s Illuminate\Bus\Queueable and Illuminate\Contracts\Queue\ShouldQueue:

   use Illuminate\Bus\Queueable;
   use Illuminate\Contracts\Queue\ShouldQueue;
   
   class SendReminderEmail implements ShouldQueue
   {
       use Queueable;
   
       public function handle()
       {
           // Job logic here
       }
   }
   

2. Dispatching Jobs Use Symfony’s service container to access the dispatcher:

   $this->dispatcher->dispatch(new ProcessPodcast());
   $this->dispatcher->dispatch(new ProcessPodcast)->delay(10);  // Delay in seconds
   

3. Queue Configuration Configure the queue connection in config.yml (e.g., database, redis):

   cu_labs_illuminate:
       queue:
           connections:
               redis:
                   driver: redis
                   host: 127.0.0.1
                   port: 6379
               database:
                   driver: database
                   table: jobs
                   database: %database_name%
   

4. Handling Failures Implement Illuminate\Contracts\Queue\ShouldBeUnique or Illuminate\Contracts\Queue\AfterCommit for retries/unique jobs:

   class ProcessPodcast implements ShouldQueue, ShouldBeUnique
   {
       // ...
   }
   

Scheduling Workflows

1. Implement ScheduleKernelInterface Modify AppKernel to define scheduled tasks:

   use CULabs\IlluminateBundle\Bridge\Scheduling\ScheduleKernelInterface;
   
   class AppKernel extends Kernel implements ScheduleKernelInterface
   {
       public function schedule($command)
       {
           // Define Laravel-style schedules
           $command->call('podcast:download')->daily();
           $command->call('analytics:report')->weekly();
       }
   }
   

2. Define Console Commands Create Symfony commands (compatible with Laravel’s Artisan):

   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class DownloadPodcastCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           // Command logic
       }
   }
   

3. Register Commands Add commands to Symfony’s service container (e.g., in services.yml):

   services:
       app.command.download_podcast:
           class: App\Command\DownloadPodcastCommand
           tags:
               - { name: console.command }
   

4. Run the Scheduler Add a cron job or Symfony event listener to trigger the scheduler periodically:

   * * * * * php /path/to/bin/console culabs:schedule:run
   

Integration Tips

1. Leverage Laravel’s Queue Workers Run Laravel’s queue worker alongside Symfony:

   php /path/to/vendor/bin/laravel-queue-worker --queue=redis
   

2. Shared Services Reuse Laravel services (e.g., Mail, Cache) in Symfony:

   $mailer = $this->get('cu_labs_illuminate.mailer');
   $mailer->send('emails.welcome', [], function ($message) {
       $message->to('user@example.com');
   });
   

3. Event Listeners Use Laravel’s event system in Symfony:

   use CULabs\IlluminateBundle\Bridge\Events\Dispatcher;
   
   class UserRegisteredListener
   {
       public function __construct(Dispatcher $dispatcher)
       {
           $dispatcher->listen('user.registered', function () {
               // Handle event
           });
       }
   }
   

Gotchas and Tips

Pitfalls

1. Configuration Mismatch

   • Ensure cu_labs_illuminate config matches Laravel’s expected structure (e.g., app.key must be 32 chars).
   • Fix: Validate config against Laravel’s defaults or use php artisan config:dump (if available).

2. Queue Connection Issues

   • If the queue driver (e.g., Redis) isn’t properly configured, jobs will fail silently.
   • Fix: Verify connection settings in config.yml and test with:

     php /path/to/vendor/bin/laravel-queue:work --queue=redis --once
     

3. Scheduler Not Triggering

   • The scheduler (culabs:schedule:run) must be called manually or via cron.
   • Fix: Add a cron entry:

     * * * * * cd /path/to/project && php bin/console culabs:schedule:run >> /dev/null 2>&1
     

4. Dependency Conflicts

   • Mixing Symfony and Laravel versions may cause issues (e.g., monolog, symfony/console).
   • Fix: Pin versions in composer.json:

     "require": {
         "symfony/console": "~3.4",
         "monolog/monolog": "~1.26"
     }
     

5. Job Serialization

   • Complex objects in jobs may not serialize correctly.
   • Fix: Use __serialize()/__unserialize() or simplify job payloads:

     public function __serialize()
     {
         return ['user_id' => $this->user->id];
     }
     

Debugging Tips

1. Queue Logs Enable Laravel’s queue logging in config.yml:

   cu_labs_illuminate:
       queue:
           log: true
           log_file: /path/to/queue.log
   

2. Scheduler Debugging Run the scheduler manually to test:

   php bin/console culabs:schedule:run --verbose
   

3. Job Inspection Check failed jobs in the database (if using database driver):

   SELECT * FROM jobs WHERE failed_at IS NOT NULL;
   

4. Service Container Dumping Inspect available services:

   php bin/console debug:container | grep culabs
   

Extension Points

1. Custom Queue Drivers Extend the bundle to support additional drivers (e.g., AWS SQS):

   // src/CULabs/IlluminateBundle/DependencyInjection/Configuration.php
   $builder->appendNode('queue.connections')
       ->children()
           ->arrayNode('sqs')
               ->children()
                   ->scalarNode('key')->end()
                   ->scalarNode('secret')->end()
               ->end()
           ->end();
   

2. Event Listeners Add custom listeners to Laravel’s event system:

   use CULabs\IlluminateBundle\Bridge\Events\Dispatcher;
   
   class CustomEventListener
   {
       public function __construct(Dispatcher $dispatcher)
       {
           $dispatcher->listen('custom.event', [$this, 'handle']);
       }
   
       public function handle($event)
       {
           // Handle custom event
       }
   }
   

3. Console Command Extensions Create reusable command traits or base classes:

   use Symfony\Component\Console\Command\Command;
   use CULabs\IlluminateBundle\Bridge\Console\LaravelCommand;
   
   abstract class BaseLaravelCommand extends LaravelCommand
   {
       protected