File System Watcher Laravel Package

Getting Started

Install the package with composer require spatie/file-system-watcher. Then install the required Node.js dependency: npm install chokidar. The core use case is to run a PHP script that waits for filesystem events — e.g., triggering image processing when new uploads appear. Start with Watch::path($dir)->onFileCreated(fn($path) => process($path))->start() and run it as a long-lived CLI command (e.g., via php artisan watch:files).

Implementation Patterns

• CLI watchers in Laravel: Create an artisan command (php artisan make:command WatchForFiles) that wraps Watch::path(...)->on...()->start() and manage it with Supervisor or systemd for resilience.
• Event-driven pipelines: Chain multiple handlers for the same event (e.g., onFileUpdated to update search index, then re-cache a rendered view).
• Conditional watching: Use shouldContinue(fn() => !Storage::disk('local')->exists('shutdown.flag')) to implement controlled shutdowns (e.g., during deploys).
• Multi-path monitoring: Watch paths(base_path('app'), storage_path('app/public')) to trigger regeneration of configs/views or sync assets.
• Delayed processing: Combine ->setIntervalTime(500000) with file-existence checks to avoid acting on partially-written files (especially important for large uploads).

Gotchas and Tips

• The start() method blocks indefinitely — any code after it (including finally blocks) won’t run unless interrupted. Always use pcntl_signal or graceful shutdown via shouldContinue() to handle SIGTERM/SIGINT safely.
• Chokidar requires Node.js ≥ v14. If npm install chokidar fails, the watcher silently won’t work — verify node/npm are in PATH via php artisan tinker >>> exec('which node');.
• File-event timing: Updates may fire multiple times for atomic writes (e.g., file_put_contents). Debounce with a short delay or use a stateful accumulator (e.g., SplObjectStorage) to avoid duplicate processing.
• On macOS, inotify-based watchers (e.g., via chokidar-fsevents) are default, but if watching across network mounts, explicitly configure usePolling: true via a custom Node wrapper — this package doesn’t expose chokidar options yet.
• Test with phpunit + tempnam()/symlink() directories; avoid testing against real project directories to prevent side effects.
• For long-running processes, monitor memory usage — each registered closure and internal event queue may accumulate over time; call gc_collect_cycles() periodically if needed.