Vista Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require chege-simon/vista
   

   Publish the config file (if available):

   php artisan vendor:publish --provider="ChegeSimon\Vista\VistaServiceProvider"
   

2. Configuration:

   • Check config/vista.php for default settings (e.g., queue connection, job timeout).
   • Ensure your AppServiceProvider boots the package:

     Vista::boot();
     

3. First Use Case:

   • Replace a scheduled command with a "job" for Horizon-like visibility:

     use ChegeSimon\Vista\Jobs\ScheduleJob;
     
     ScheduleJob::dispatch(new \App\Jobs\YourScheduledTask)
         ->delay(now()->addMinutes(5))
         ->onConnection('database');
     

4. Verify:

   • Run php artisan queue:work to process jobs.
   • Check the vista_jobs table in your database for job statuses.

Implementation Patterns

Workflow Integration

1. Command-to-Job Migration:

   • Convert scheduled commands to jobs:

     // Before (Command)
     $schedule->command('your:command')->everyMinute();
     
     // After (Job)
     $schedule->call(function () {
         ScheduleJob::dispatch(new YourScheduledTask);
     })->everyMinute();
     

2. Dynamic Scheduling:

   • Use delay() or at() for time-based jobs:

     ScheduleJob::dispatch(new YourTask)
         ->delay(now()->addHours(2))
         ->onQueue('high');
     

3. Batch Processing:

   • Group related jobs under a single "batch" for tracking:

     $batch = Vista::batch(['batch_id' => 'report-2023']);
     $batch->dispatch(new GenerateReportJob);
     $batch->dispatch(new SendReportJob);
     

4. Event Listeners:

   • Hook into job lifecycle events (e.g., JobProcessed, JobFailed):

     Vista::listen('JobProcessed', function ($job) {
         Log::info("Job {$job->id} completed");
     });
     

Common Use Cases

• Monitoring: Use the vista:list artisan command to inspect pending/failed jobs.
• Retry Logic: Implement custom retry logic via shouldRetry() in your job class.
• Notifications: Extend the package to send Slack/email alerts for failed jobs.

Gotchas and Tips

Pitfalls

1. Database Dependency:

   • Unlike Horizon, this package requires a database connection for job tracking. Ensure your queue connection is configured correctly in config/queue.php.

2. Missing Horizon Features:

   • No built-in web dashboard (unlike Horizon). Use telescope or custom views for monitoring.
   • No supervisor integration; rely on Laravel’s queue:work or queue:listen.

3. Job Serialization:

   • Custom job classes must implement ShouldQueue and be serializable. Avoid non-serializable dependencies (e.g., closures, resources).

4. Config Overrides:

   • The package may not auto-discover all Horizon config options. Check config/vista.php for missing settings (e.g., max_jobs, max_timeouts).

Debugging Tips

• Job Stuck in "Processing" State:

  • Manually update the finished_at column in vista_jobs to force completion.
  • Check for deadlocks in your database transactions.

• Failed Jobs Not Retrying:

  • Verify shouldRetry() is implemented in your job class:

    public function shouldRetry()
    {
        return $this->attempts() < 3;
    }
    

• Missing Jobs in Database:

  • Ensure your queue worker is connected to the correct database (e.g., QUEUE_CONNECTION=database in .env).

Extension Points

1. Custom Job Tables:

   • Override the default vista_jobs table by binding a custom JobRepository:

     Vista::extend('custom', function () {
         return new CustomJobRepository();
     });
     

2. Job Middleware:

   • Add middleware to jobs via the handle() method:

     public function handle()
     {
         $this->middleware(YourMiddleware::class);
         // Job logic
     }
     

3. Event Customization:

   • Extend the JobProcessed/JobFailed events to add custom payloads:

     Vista::extendEvent('JobFailed', function ($job, $exception) {
         return new CustomJobFailed($job, $exception, ['custom_data' => 'value']);
     });
     

4. Queue Worker Hooks:

   • Override the default worker behavior by binding a custom Worker class:

     Vista::worker(function () {
         return new CustomWorker();
     });