Laravel Horizon Watcher Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/laravel-horizon-watcher
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Spatie\HorizonWatcher\HorizonWatcherServiceProvider"
   

2. First Use Case: Run the horizon:watch command in your terminal:

   php artisan horizon:watch
   

   • This starts Horizon in watch mode, automatically restarting when PHP files in your project change.
   • Ideal for local development where you frequently modify job classes, workers, or Horizon-related configurations.

3. Where to Look First:

   • Config File: config/horizon-watcher.php (if published) to customize watched paths or behavior.
   • Command: php artisan horizon:watch --help to explore options like --ignore or --path.

Implementation Patterns

Usage Patterns

1. Daily Workflow:

   • Replace manual Horizon restarts with php artisan horizon:watch during development.
   • Example:

     php artisan horizon:watch --ignore="tests/*" --path="app/Jobs,app/Workers"
     

     • Watches only app/Jobs and app/Workers directories, ignoring tests/.

2. Integration with Laravel Forge/Valet:

   • Add the command to your local environment setup scripts (e.g., package.json or Makefile).
   • Example Makefile:

     watch-horizon:
         php artisan horizon:watch --ignore="storage/*"
     

3. CI/CD Exclusion:

   • Exclude the package from production builds (already handled by the package’s local-only design).
   • Ensure .env has APP_ENV=local when using the command.

Workflows

• Pair with nodemon or entr: For advanced users, combine with other tools for broader file watching:

  # Watch PHP files and trigger horizon:watch on changes
  entr -r 'php artisan horizon:watch' app/
  

• Custom Paths: Override default paths (e.g., vendor directories) in config/horizon-watcher.php:

  'paths' => [
      app_path('Jobs'),
      app_path('Workers'),
      base_path('routes/channels.php'), // Include Horizon channel routes
  ],
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Watching too many files (e.g., entire vendor/) can slow down file system operations.
   • Fix: Use --ignore to exclude unnecessary directories.

2. Stale Processes:

   • If Horizon crashes or the watcher hangs, manually kill processes:

     pkill -f "php artisan horizon"
     

   • Tip: Add a cleanup step in your Makefile:

     clean-horizon:
         pkill -f "php artisan horizon" || true
     

3. Permissions Issues:

   • Ensure the user running the command has read/write access to watched directories.
   • Fix: Run as the same user as your Laravel app (e.g., www-data on Linux).

4. Ignored Files Not Working:

   • The --ignore flag uses glob patterns. Test patterns in isolation:

     php artisan horizon:watch --ignore="tests/*,storage/*"
     

Debugging

• Verbose Mode: Run with -v for debug output:

  php artisan horizon:watch -v
  

• Log File: Check storage/logs/laravel.log for watcher errors (e.g., permission denied).

Extension Points

1. Custom Watcher Logic: Extend the Spatie\HorizonWatcher\Commands\WatchHorizon command to add pre/post-restart hooks:

   // app/Console/Commands/ExtendedWatchHorizon.php
   namespace App\Console\Commands;
   
   use Spatie\HorizonWatcher\Commands\WatchHorizon;
   
   class ExtendedWatchHorizon extends WatchHorizon {
       protected function beforeRestart() {
           // Custom logic (e.g., log restart)
           info('Restarting Horizon due to file changes...');
       }
   }
   

   Register the command in app/Console/Kernel.php:

   protected $commands = [
       \App\Console\Commands\ExtendedWatchHorizon::class,
   ];
   

2. Environment-Specific Config: Use Laravel’s environment-based config to disable the watcher in non-local environments:

   'enabled' => env('APP_ENV') === 'local',
   

3. Docker/Containerized Environments:

   • Mount host directories into containers to watch local changes:

     # docker-compose.yml
     services:
       app:
         volumes:
           - ./:/var/www/html:cached
     

   • Run the watcher inside the container:

     docker exec -it app php artisan horizon:watch