Watch Files Laravel Package

Product Decisions This Supports

• Incremental build & asset pipelines: Decide whether a compile/transpile step is needed at all on a given run by comparing a directory snapshot against the last one, rather than unconditionally rebuilding. This is the classic "only rebuild what changed" primitive.
• Cache invalidation strategy: Drive cache-busting keys for config, compiled views, route caches, or generated manifests off a stateless directory hash. This is directly relevant to Laravel's config:cache / view:cache / route:cache lifecycle and to any custom compiled-artifact directory.
• Deployment and drift detection: Answer "has anything under this path changed since the last deploy?" in a cron or health-check context, without a resident daemon. Useful for shared-hosting or container environments where long-running watchers are impractical.
• Scheduled task gating: Let scheduled jobs (Schedule::call) short-circuit when a watched directory is unchanged, cutting wasted queue/CPU on a low-traffic app.
• Developer-tooling and DX features: If your product is a CLI, admin panel, or scaffolding tool, this supports a "reload on source change" affordance without requiring inotify extensions or a persistent worker (Octane/Swoole-adjacent, or plain PHP-FPM environments).
• Buy vs. build: This is a candidate to avoid building in-house only if its stateless model matches your execution model (short-lived requests, cron, CI). If your product genuinely needs event-driven watching, this is the wrong side of the buy-vs-build line.

When to Consider This Package

Consider it when all of the following hold:

• Your process is short-lived — a web request, a queue job, a scheduled command, a CI step — and you want change detection without a supervisor-managed watcher.
• You need "changed since last check" semantics, not "tell me the instant a file changes." Stateless comparison is inherently snapshot-based; there is no event stream.
• The watched set is small-to-moderate and on local or reliably-mountable storage. Polling-style directory hashing scales poorly and behaves unpredictably on network filesystems or object-store mounts.
• You are comfortable vendoring or forking it. With 9 stars, zero dependents, and a minimal score, treat this as a reference implementation, not a supported dependency.

Look elsewhere when:

• You need real-time reaction (hot reload, live asset serving, watch-mode dev servers). Use inotify/fswatch, spatie/file-watcher, Chokidar via Node, or a proper supervisor-managed daemon.
• You need maintained, security-patched dependencies. Zero dependents means zero community validation; there is no signal on PHP 8.3/8.4 compatibility, and no security response process.
• Your watched tree is large or deeply nested — full-tree hashing per request will show up in your p95 latency.
• You need precision about what changed (file-level diffing for selective recompilation). A directory-level hash tells you "something changed," not "these three files changed."
• Symlinks, permissions, or VCS metadata matter to correctness — audit its traversal behavior against Symfony Finder before trusting it.

Recommended posture: spike it, don't adopt it. Wrap it behind a narrow internal interface (ChangeDetector) so you can substitute a Finder-based implementation or a real watcher later without touching call sites. Budget a day to read the source and confirm its comparison algorithm (mtime vs. content hash) and its handling of deleted files.

How to Pitch It (Stakeholders)

For executives: This is a small, low-risk utility that lets us skip work when nothing has changed — no rebuilds, no cache warming, no redundant scheduled jobs. The upside is real but modest: reduced compute and faster deploys on unchanged code. The caveat is that it is an unmaintained, single-author library with essentially no adoption (9 stars, zero dependents), so I am not proposing it as a production dependency. I am proposing we spend roughly one engineer-day evaluating its approach and, if it fits, implement the same stateless snapshot check ourselves in about 100 lines behind an internal interface. The strategic value is the pattern — cheap change detection without infrastructure — not the package.

For engineering: The pitch is a stateless hasChanged(path, snapshot) primitive. No daemon, no supervisor, no inotify extension requirement — it works inside a normal PHP-FPM request or a cron tick. That makes it viable in environments where we cannot run a long-lived watcher, which is most of our estate. Concrete first applications: gating view:cache/config:cache rebuilds, short-circuiting the asset compile step in CI, and guarding a nightly scheduled job. Risks are equally concrete: it is effectively unmaintained, so we fork or reimplement rather than depend; it is snapshot-based, so it is unsuitable for hot-reload UX; and full-tree hashing must be scoped to a small set of paths or it will appear in our latency budget. Recommendation: prototype behind a ChangeDetector interface, measure the hashing cost on our largest watched directory, and only then decide between adopting, forking, or replacing with a Symfony Finder-based equivalent.