Resource Watcher Laravel Package

Product Decisions This Supports

• Build vs. buy for internal tooling. This is a "buy" (adopt) candidate for any non-differentiating capability that needs to react to file changes — hot reload, asset regeneration, cache invalidation, log tailing, config reloading. The core loop (poll a set of paths on an interval, hash each resource, diff against a persisted cache, emit created/modified/deleted) is exactly the kind of plumbing that looks trivial in a ticket and becomes a 2–3 week tail of edge cases in reality: debouncing, atomic writes, renamed files, deleted-then-recreated paths, symlinks, permission errors on partial reads. Adopting a library converts that tail into an integration task.

• Feature scoping: file-change reaction as an enabler, not a product. If the roadmap item is "auto-recompile theme assets in the admin preview" or "reload worker config without a deploy," the file-watching mechanism itself is invisible to the customer. That argues strongly for the thinnest viable dependency rather than a bespoke subsystem the team then owns forever. This package's scope — polling plus checksums plus events — is narrowly matched to that need and does not drag in a daemon, a supervisor, or an inotify extension requirement.

• Roadmap sequencing and risk. The library is MIT-licensed, has no paid tier, no vendor lock-in, and no runtime service dependency — it is a Composer package. That makes it cheap to try and cheap to abandon: a spike can validate the product behavior in days, and ripping it out later is a contained refactor behind an interface. This is the shape of dependency you want under an uncertain roadmap item, and it lets you commit to a demo date before committing to an architecture.

• Use cases worth putting in front of the team:

  • Local and staging hot-reload for a Laravel view/asset pipeline where the deploy target has no Node toolchain.
  • Cache and config invalidation — watch config/, translation files, or a feature-flag file and flush the relevant cache store on change, instead of a cron that flushes blindly.
  • Build and CI pipelines that need a "wait until the artifact set settles, then run the next stage" step, where the checksum-plus-resource-cache design naturally suppresses duplicate triggers.
  • Tenant or content-directory monitoring — watching per-tenant directories for uploaded or dropped files and enqueuing jobs on creation and cleanup on deletion.

• Explicitly not supported as a decision: real-time guarantees. Because detection is polling plus checksum comparison rather than filesystem notifications, the product cannot honestly promise sub-second reaction or low CPU cost on large trees. If a roadmap item's success criteria include latency or footprint numbers, this package is the wrong lever and the decision should be scoped as "acceptable staleness, tuned by interval."

• Dependency-footprint decision. It leans on Symfony Finder and Symfony EventDispatcher — components Laravel already ships or commonly carries. That means near-zero marginal install weight and a callback model (EventDispatcher) that Laravel engineers will read instantly, which lowers review friction and the cost of the code review that gates the merge.

When to Consider This Package

Adopt when most of the following hold:

• The trigger is a periodic or near-real-time reaction, not a hard real-time one. Batched or interval-driven reaction is acceptable to the product (e.g., "within a few seconds," not "within 50ms").
• The watched set is bounded and modest. Hundreds to low thousands of files. The polling-and-hashing loop is O(files) per tick, so cost scales with the tree size times the poll frequency; large monorepos or media libraries will burn CPU.
• The team wants Symfony-style composition. Your engineers already think in Finder constraints and EventDispatcher listeners, and you want the watched set defined declaratively ("everything under resources/views except *.swp") rather than hardcoded.
• Duplicate-event suppression matters to the product. The resource cache that persists hashes across ticks is the differentiating detail here — it prevents the "one save fires five rebuilds" behavior that makes internal tools feel broken.
• The use is internal, dev-facing, or behind a queue. You are not putting this on a customer-facing request path.

Look elsewhere when:

• You need genuine filesystem events. If the requirement is instant reaction, low idle CPU, or watching tens of thousands of paths, wrap inotify (Linux), FSEvents (macOS), or Watchman/Chokidar behind the same interface. Polling will not get you there, and no amount of interval tuning fixes the architectural gap.
• Maintenance posture is a blocker. The last release dates to mid-2020 and the project sits at roughly 68 stars — it is a small, quiet, effectively single-maintainer library. Treat it as vendored-and-owned: confirm it runs on your PHP version and your Laravel version before adoption, budget for forking it if a PHP upgrade breaks it, and do not assume upstream will ship a fix. This is acceptable for dev tooling and unacceptable for anything on the critical path.
• You need Windows parity at scale. Cross-platform behavior around file locks and atomic-write semantics is the classic weak spot in polling watchers; validate on every OS you claim to support before committing the story.
• A framework-native or platform-native answer already exists. In a Laravel context, php artisan serve-adjacent tooling, Vite/HMR, or queue workers with restart-on-deploy may already solve the underlying user need without a new dependency. Check that the product requirement isn't already met before adding a watcher.
• You need durable, auditable event history. This dispatches in-process callbacks; it is not an event log. If the product needs replay, ordering guarantees, or an audit trail of file changes, that is a different system.

How to Pitch It (Stakeholders)

To executives: We can satisfy a class of "the app should react when files change" requirements — hot reload, config and cache refresh, pipeline gating — by adopting a small MIT-licensed PHP library instead of building the mechanism ourselves. It is free, adds no service, no vendor relationship, and no infrastructure. The expected saving is a few weeks of engineering per use case, and the exit cost is low: it sits behind an interface, so if it stops being maintained we replace it in a contained piece of work rather than a rewrite. The tradeoff to accept knowingly is that reaction is interval-based, not instant — fine for developer and internal tooling, not fine for anything with a latency promise to a customer.

To engineering: Polling loop over Finder-filtered paths, checksums each resource, diffs against a persisted hash cache, and dispatches created/modified/deleted through Symfony's EventDispatcher — so your handlers are ordinary listeners and the watched set reads like a Finder query. It ships no daemon and needs no PHP extension. Two things to verify before we merge: current PHP and Laravel compatibility (last upstream release was 2020, low activity), and the polling cost on our largest watched tree. Plan to own the dependency — pin the version, isolate it behind our own watcher interface, and assume we fork rather than wait if a framework upgrade breaks it. For anything needing sub-second reaction or six-figure path counts, we go to inotify/FSEvents and keep the same interface.