Horizon Laravel Package

Technical Evaluation

Architecture Fit

Laravel Horizon is a first-class fit for Laravel-based applications relying on Redis queues (e.g., redis, database drivers are unsupported). It replaces Laravel’s default queue worker with a supervisor-based system, enabling:

• Real-time monitoring of job throughput, failures, and runtime via a dashboard.
• Fine-grained configuration (e.g., concurrency, batching, timeouts) via config/horizon.php.
• Batch processing and job tagging for granular control.
• Supervisor management (scaling workers dynamically via supervisor.json).

Key architectural benefits:

• Decouples queue workers from the web server (e.g., runs in background via Supervisor).
• Reduces manual intervention for scaling (auto-adjusts workers based on queue load).
• Enhances observability with metrics, logs, and a UI for debugging.

Anti-patterns to avoid:

• Not for non-Redis queues: Horizon is Redis-specific; alternatives like laravel-queue-worker exist for other drivers.
• Overhead for simple apps: If queues are trivial (e.g., <10 jobs/day), Horizon’s complexity may be unnecessary.

Integration Feasibility

Prerequisites:

1. Laravel 10/11/12 (or 9.x with compatibility layer).
2. Redis (v6+ recommended) with a dedicated connection (avoid sharing with caching).
3. Supervisor (for production; queue:work falls back to CLI workers in dev).

Integration steps:

1. Installation:

   composer require laravel/horizon
   php artisan horizon:install
   

2. Configure:
   • Update config/horizon.php (e.g., set supervisor to true, define concurrency, batch sizes).
   • Define Redis connection in .env (e.g., REDIS_URL=redis://redis:6379).
3. Deploy Supervisor:
   • Configure /etc/supervisor/conf.d/horizon.conf (example provided in Horizon docs).
   • Start Supervisor: supervisorctl reread && supervisorctl update && supervisorctl start horizon:*.

Compatibility:

• Laravel Queues: Works with all queue drivers except database/sync (Redis-only).
• Job Classes: Must extend Illuminate\Bus\Queueable (standard for Laravel jobs).
• Middleware: Supports dispatchAfterCommit, onQueue, etc.

Potential conflicts:

• Existing Supervisor configs: May require merging with existing worker processes.
• Redis memory: High job volumes can strain Redis (monitor with redis-cli --stat).

Technical Risk

Critical questions for the TPM:

1. Queue volume: How many jobs/day? Horizon’s dashboard may lag with >10K jobs/hour.
2. Redis setup: Is Redis clustered? What’s the memory limit?
3. Deployment model: Will Supervisor run on the same host as the app? If not, ensure network latency is minimal.
4. Fallback strategy: How will you handle Horizon failures (e.g., Redis outage)? Retain queue:work as a backup.
5. Custom metrics: Do you need to extend Horizon’s dashboard (e.g., Grafana integration)?

Integration Approach

Stack Fit

Horizon is optimized for:

• Laravel ecosystems using Redis queues (e.g., e-commerce, SaaS, real-time systems).
• Microservices where queue reliability is critical.
• Teams prioritizing observability over minimal setup.

Stack compatibility:

Non-compatible stacks:

• Non-Redis queues: Use laravel-queue-worker or pestle instead.
• Serverless: Horizon assumes persistent processes; consider SQS + Lambda.

Migration Path

Phase 1: Pilot (Dev/Staging)

1. Replace queue:work:
   • Stop existing workers: pkill -f queue:work.
   • Start Horizon in dev mode: php artisan horizon.
2. Validate:
   • Test job throughput, failures, and dashboard metrics.
   • Compare performance with queue:work --daemon.
3. Configure:
   • Tune concurrency, batch, and timeout in horizon.php.
   • Set up Supervisor for staging.

Phase 2: Production Rollout

1. Blue-green deployment:
   • Run Horizon alongside old workers during a maintenance window.
   • Monitor Redis memory and job processing rates.
2. Supervisor setup:
   • Deploy /etc/supervisor/conf.d/horizon.conf (example below):

     [program:horizon-worker]
     process_name=%(program_name)s_%(process_num)02d
     command=php /var/www/artisan horizon:work
     autostart=true
     autorestart=true
     numprocs=8
     user=www-data
     numproc=8
     

   • Start Supervisor: supervisorctl reread && supervisorctl update.
3. Monitor:
   • Use supervisorctl tail -f horizon-worker stdout for logs.
   • Check Horizon dashboard for anomalies.

Phase 3: Optimization

• Scale workers: Adjust numprocs based on CPU/memory usage.
• Batch tuning: Increase batch size for high-volume queues (e.g., batch:100).
• Alerting: Set up alerts for failed jobs or high latency.

Compatibility

Known limitations:

• No distributed tracing: Add OpenTelemetry manually if needed.
• No queue prioritization: Use job tags + custom sorting in Redis.
• Dashboard customization: Limited to Blade templates (advanced UX requires JS overrides).

Sequencing

Recommended order:

1. Upgrade Laravel: Ensure compatibility (e.g., Laravel 11 for Horizon 5.45+).
2. Redis upgrade: Patch to v6.x if using older versions.
3. Pilot Horizon: Test in staging with a subset of jobs.
4. Supervisor setup: Deploy in parallel with old workers.
5. Monitor: Validate metrics for 1 week before full cutover.
6. Deprecate old workers: Remove queue:work from deployment scripts.

Rollback plan:

• Keep queue:work in CI/CD until Horizon is stable.
• Use php artisan queue:flush to clear Horizon-managed queues if needed.

Operational Impact

Maintenance

Pros:

• Centralized config: All worker settings in horizon.php (version-controlled).
• Supervisor management: Easy to scale/restart workers via supervisorctl.
• Dashboard-driven: No need for custom scripts to monitor queues.

Cons:

• Redis dependency: Requires Redis expertise for tuning (e.g., maxmemory-policy).
• **