Laravel Horizon Watcher Laravel Package

Technical Evaluation

Architecture Fit

• Local Development Focus: The package is explicitly designed for local development environments, not production. It integrates with Laravel Horizon (a queue worker supervisor) to auto-restart workers on file changes, eliminating manual restarts during job debugging.
• Horizon Dependency: Requires Laravel Horizon (v5.0+) as a prerequisite, meaning it fits only in architectures using Horizon for queue workers. Not applicable for raw Laravel queues or alternative queue systems (e.g., RabbitMQ, SQS).
• Event-Driven: Leverages filesystem events (via spatie/flysystem-event-handler or similar) to trigger restarts, which is lightweight but limited to PHP file changes (excludes config/environment changes).

Integration Feasibility

• Minimal Boilerplate: Single Artisan command (horizon:watch) with zero configuration required. Integration reduces to:

  composer require spatie/laravel-horizon-watcher
  php artisan horizon:watch
  

• Horizon Compatibility: Works with Horizon’s existing configuration (e.g., .env, config/horizon.php). No conflicts with other queue supervisors (e.g., Supervisor, systemd).
• Local-Only Scope: Explicitly not for production. Requires explicit exclusion from CI/CD pipelines or deployment scripts.

Technical Risk

• False Positives: Filesystem events may trigger unnecessary restarts (e.g., IDE temp files, node_modules). Mitigation: Exclude paths via Horizon’s ignore_files or custom event filtering.
• State Loss: Horizon workers are abruptly terminated on file changes, potentially losing in-memory state (e.g., cached jobs, connections). Risk is low for stateless jobs but critical for long-running workers.
• Dependency Bloat: Adds ~10KB to local dev environments; negligible but worth noting for teams with strict package limits.
• Edge Cases:
  • Symlinked Files: May not detect changes in symlinked directories without additional configuration.
  • Docker/WSL: Filesystem event detection may behave differently in containerized or WSL environments (test required).

Key Questions

1. Workload Profile: Are jobs stateless (e.g., short-lived commands) or stateful (e.g., long-running processes with in-memory data)?
2. Environment Scope: Is this only for local dev? If yes, how will it be gated (e.g., .env checks, CI exclusions)?
3. Horizon Configuration: Are there existing ignore_files or custom event handlers that could conflict?
4. Monitoring: How will teams debug false restarts or missed file changes (e.g., logging, metrics)?
5. Alternatives: Could nodemon or entr + custom scripts achieve the same with more control?

Integration Approach

Stack Fit

• Laravel Ecosystem: Native fit for Laravel projects using Horizon (v5.0+). No conflicts with other Laravel packages.
• Local Dev Tools: Complements existing workflows like:
  • Laravel Valet/Vapor: Works seamlessly with Valet’s auto-reload.
  • Docker: Requires volume mounts for filesystem events to trigger (test in CI/CD).
  • IDE Integration: Pairs well with PHPStorm’s "Regenerate Code Coverage" or VSCode’s live reload.
• Non-Horizon Queues: Not applicable. Requires Horizon’s supervisor layer.

Migration Path

1. Prerequisite Check:
   • Ensure Horizon is installed (laravel/horizon).
   • Verify Horizon is configured in .env (QUEUE_CONNECTION=redis).
2. Installation:

   composer require spatie/laravel-horizon-watcher --dev
   

3. Usage:
   • Replace manual php artisan horizon with:

     php artisan horizon:watch
     

   • Add to package.json scripts (optional):

     "scripts": {
       "dev:horizon": "php artisan horizon:watch"
     }
     

4. Exclusions (if needed):
   • Extend Horizon’s ignore_files in config/horizon.php:

     'ignore_files' => [
         app_path('Horizon/IgnoredDirectory/*'),
         storage_path('logs/*'),
     ],
     

Compatibility

• PHP Version: Requires PHP 8.0+ (same as Horizon v5.0+).
• Horizon Version: Tested with Horizon v5.0–latest. May need adjustments for major Horizon versions.
• Filesystem: Relies on inotify (Linux) or equivalent (macOS/Windows). Docker users may need --privileged or custom event handlers.
• CI/CD: Must be excluded from pipelines (e.g., via .env checks or script guards):

  if [ "$APP_ENV" != "local" ]; then exit 0; fi
  php artisan horizon:watch
  

Sequencing

1. Local Setup:
   • Install package → Test horizon:watch → Verify auto-restarts.
2. Team Adoption:
   • Document in CONTRIBUTING.md or DEVELOPMENT.md.
   • Add to onboarding scripts (e.g., bin/local-setup).
3. Monitoring:
   • Log restarts to storage/logs/horizon-watcher.log (customizable).
   • Alert on excessive restarts (e.g., >5/minute).

Operational Impact

Maintenance

• Low Overhead: No cron jobs, database migrations, or complex dependencies.
• Updates: Passive (updates via Composer). Test after major Horizon releases.
• Debugging:
  • False Restarts: Check storage/logs/laravel.log for event triggers.
  • Missed Changes: Verify filesystem event support in the environment (e.g., inotify limits on Linux).

Support

• Local-Specific: Support burden is isolated to local dev environments. No production impact.
• Documentation: README is sufficient; may need internal runbooks for:
  • "Horizon won’t restart after file changes."
  • "How to exclude directories."
• Vendor Support: Spatie provides MIT-licensed open-source support (community/issue tracker).

Scaling

• Local Only: No scaling concerns; designed for single-developer or small-team local use.
• Team Sync: Risk of desync if multiple devs run horizon:watch on shared files (e.g., Docker volumes). Mitigation:
  • Use unique Horizon queues per dev (QUEUE_CONNECTION=redis-dev1).
  • Document "one Horizon instance per developer" rule.

Failure Modes

Ramp-Up

• Onboarding Time: <10 minutes for basic setup.
• Training Needed:
  • For Devs: "Replace horizon with horizon:watch in your workflow."
  • For Tech Leads: "This is local-only; no production changes."
• Adoption Barriers:
  • Resistance to Change: Some devs may prefer manual restarts. Address with:
    • Demo showing time saved (e.g., "No more Ctrl+C + horizon").
    • A/B testing: Compare debug times with/without the package.
  • False Positives: Requires initial tuning of ignore_files.