Asynchronous Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dlakomski/asynchronous
   

   Ensure simplebus/simple-bus:^2.0 is also installed (dependency).

2. Service Provider Register the package in config/app.php under providers:

   Dalakomski\Asynchronous\AsynchronousServiceProvider::class,
   

3. Publish Config (Optional)

   php artisan vendor:publish --provider="Dalakomski\Asynchronous\AsynchronousServiceProvider" --tag="config"
   

   Default config is minimal; customize as needed.

4. First Use Case: Dispatching a Job

   use Dalakomski\Asynchronous\Jobs\Job;
   
   // Define a job (must extend Dalakomski\Asynchronous\Jobs\Job)
   class SendEmailJob extends Job {
       public $email;
       public function __construct(string $email) { $this->email = $email; }
       public function handle() { /* ... */ }
   }
   
   // Dispatch asynchronously
   SendEmailJob::dispatch('user@example.com');
   

Implementation Patterns

Core Workflow: Async Processing

1. Job Dispatching

   • Use Job::dispatch(...) for one-off tasks.
   • For bulk operations, batch jobs with Job::dispatchMany([...]).

2. Queue Integration

   • Under the hood, uses Laravel’s queue system (supports database, redis, etc.).
   • Configure queue connection in config/asynchronous.php:

     'queue_connection' => 'redis',
     

3. Command-Based Jobs

   • Extend Dalakomski\Asynchronous\Jobs\CommandJob for CLI-like async tasks:

     class ProcessDataJob extends CommandJob {
         protected $command = 'process:data';
         public function handle() { /* ... */ }
     }
     

4. Event-Driven Async

   • Listen to events and dispatch jobs:

     Event::listen(UserRegistered::class, function ($user) {
         NotifyUserJob::dispatch($user->email);
     });
     

Advanced Patterns

• Job Chaining Use Job::dispatchAfter($nextJob) to chain dependent jobs.

  ProcessPaymentJob::dispatch($order)
      ->dispatchAfter(NotifyCustomerJob::class, $order->user->email);
  

• Retry Logic Implement shouldRetry() and retryAfter() in your job:

  public function shouldRetry(): bool { return $this->attempts < 3; }
  public function retryAfter(): int { return 60; }
  

• Job Metadata Attach metadata via setMetadata(['key' => 'value']) for tracking.

Gotchas and Tips

Pitfalls

1. Job Serialization

   • Only serializable data can be passed to jobs. Avoid closures or non-serializable objects.
   • Fix: Use primitive types or implement __serialize()/__unserialize().

2. Queue Worker Stuck?

   • Ensure the queue worker is running:

     php artisan queue:work
     

   • Check failed_jobs table for errors if jobs fail silently.

3. Missing Dependencies

   • simplebus/simple-bus must be installed. If missing, install manually:

     composer require simplebus/simple-bus
     

4. Config Overrides

   • Default config assumes Laravel’s queue system. For custom setups, override:

     'dispatcher' => \SimpleBus\Message\Dispatcher\Dispatcher::class,
     

Debugging Tips

• Log Job Execution Add Log::debug('Job started', ['job' => $this]) in handle().
• Inspect Failed Jobs

  php artisan queue:failed-table
  php artisan queue:retry <job_id>
  

• Test Async Jobs Use Job::dispatchSync() (if available) for testing without a queue.

Extension Points

1. Custom Dispatcher Bind a custom SimpleBus\Message\Dispatcher\Dispatcher in the service provider:

   $this->app->bind(
       \Dalakomski\Asynchronous\Contracts\Dispatcher::class,
       CustomDispatcher::class
   );
   

2. Job Middleware Add middleware to jobs via setMiddleware([Middleware::class]):

   class LogJobMiddleware {
       public function handle($job, $next) { /* ... */ }
   }
   

3. Event Listeners for Jobs Listen to JobStarted/JobCompleted events (if package emits them):

   Event::listen(JobStarted::class, function ($job) { /* ... */ });