Ya Queue Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require akson/ya-queue
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Akson\YaQueue\YaQueueServiceProvider::class,
   ],
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Akson\YaQueue\YaQueueServiceProvider"
   

   Update config/ya-queue.php with your Yandex.Cloud credentials and queue settings.

3. First Use Case: Basic Job Dispatch Define a job implementing Akson\YaQueue\Contracts\JobInterface:

   use Akson\YaQueue\Contracts\JobInterface;
   
   class SendEmailJob implements JobInterface
   {
       public function handle()
       {
           // Your job logic here
           Mail::to('user@example.com')->send(new WelcomeEmail());
       }
   }
   

   Dispatch the job:

   $job = new SendEmailJob();
   YaQueue::dispatch($job);
   

4. Queue Connection Configure the queue connection in config/queue.php:

   'connections' => [
       'ya-queue' => [
           'driver' => 'akson-ya-queue',
           'key' => env('YA_QUEUE_KEY'),
           'secret' => env('YA_QUEUE_SECRET'),
           'queue' => env('YA_QUEUE_NAME', 'default'),
           'endpoint' => env('YA_QUEUE_ENDPOINT', 'https://message-queue.api.cloud.yandex.net'),
       ],
   ],
   

   Use the connection in your code:

   Queue::connection('ya-queue')->dispatch($job);
   

Implementation Patterns

Workflow: Job Processing

1. Dispatching Jobs Use YaQueue::dispatch() or Queue::connection('ya-queue')->dispatch() for synchronous dispatching. For delayed jobs, use:

   YaQueue::later(now()->addMinutes(5), $job);
   

2. Handling Jobs Implement Akson\YaQueue\Contracts\JobInterface for custom jobs. The handle() method is executed when the job is processed.

3. Retry Logic Configure retry settings in config/ya-queue.php:

   'retry' => [
       'max_attempts' => 3,
       'delay' => 60, // seconds
   ],
   

   Use YaQueue::dispatch($job)->onRetry($callback) for custom retry logic.

4. Batching Jobs Dispatch multiple jobs in a batch:

   YaQueue::batch(function ($batch) {
       foreach ($users as $user) {
           $batch->dispatch(new SendEmailJob($user));
       }
   });
   

Integration Tips

1. Laravel Events Dispatch jobs from Laravel events:

   event(new UserRegistered($user));
   

   In the event listener:

   public function handle(UserRegistered $event)
   {
       YaQueue::dispatch(new SendWelcomeEmailJob($event->user));
   }
   

2. Commands Process jobs from Artisan commands:

   use Akson\YaQueue\Facades\YaQueue;
   
   class ProcessJobsCommand extends Command
   {
       public function handle()
       {
           YaQueue::process();
       }
   }
   

3. Middleware Use middleware for job-specific logic:

   YaQueue::dispatch($job)->onQueue('high-priority')->middleware([LogJobMiddleware::class]);
   

4. Monitoring Track job status with:

   $jobId = YaQueue::dispatch($job);
   $status = YaQueue::status($jobId);
   

Gotchas and Tips

Pitfalls

1. Authentication Issues

   • Ensure YA_QUEUE_KEY and YA_QUEUE_SECRET are correctly set in .env.
   • Verify the IAM role has permissions for message-queue.messages.publisher and message-queue.messages.consumer.

2. Queue Visibility

   • Jobs remain invisible to consumers for the duration of visibility_timeout (default: 30 seconds). Adjust in config/ya-queue.php:

     'visibility_timeout' => 60, // seconds
     

3. Error Handling

   • Unhandled exceptions in handle() will cause the job to fail. Use try-catch blocks or middleware to log errors:

     public function handle()
     {
         try {
             // Job logic
         } catch (\Exception $e) {
             Log::error("Job failed: " . $e->getMessage());
             throw $e;
         }
     }
     

4. Rate Limits

   • Yandex.Cloud may throttle requests. Monitor your queue metrics and adjust batch sizes if needed.

5. Serialization

   • Ensure all job payloads are serializable. Avoid passing non-serializable objects (e.g., closures, resources) directly.

Debugging Tips

1. Enable Logging Add to config/logging.php:

   'channels' => [
       'ya-queue' => [
           'driver' => 'single',
           'path' => storage_path('logs/ya-queue.log'),
           'level' => 'debug',
       ],
   ],
   

   Then configure in config/ya-queue.php:

   'log_channel' => 'ya-queue',
   

2. Test Locally Use the sync driver for local testing:

   Queue::connection('ya-queue')->onConnection('sync');
   

3. Check Job Status Use the CLI to inspect jobs:

   php artisan ya-queue:list
   php artisan ya-queue:status <job-id>
   

Extension Points

1. Custom Job Middleware Create middleware to extend job behavior:

   namespace App\Jobs\Middleware;
   
   use Akson\YaQueue\Contracts\JobMiddleware;
   
   class LogJobMiddleware implements JobMiddleware
   {
       public function handle($job, $next)
       {
           Log::info("Job dispatched: " . get_class($job));
           return $next($job);
       }
   }
   

   Register in config/ya-queue.php:

   'middleware' => [
       \App\Jobs\Middleware\LogJobMiddleware::class,
   ],
   

2. Custom Job Events Extend the package by publishing events:

   event(new JobDispatched($job));
   event(new JobProcessed($job));
   

   Listen for these events in your application.

3. Override Default Config Extend the config by publishing and modifying config/ya-queue.php:

   'default' => env('YA_QUEUE_DEFAULT', 'default'),
   'queues' => [
       'default' => [
           'name' => env('YA_QUEUE_NAME', 'default-queue'),
           'url' => env('YA_QUEUE_URL'),
       ],
       'high-priority' => [
           'name' => 'high-priority-queue',
           'url' => env('YA_QUEUE_HIGH_PRIORITY_URL'),
       ],
   ],
   

4. Custom Job Factories For complex job payloads, create a factory:

   YaQueue::dispatch((new SendEmailJobFactory($user))->create());