Product Decisions This Supports
- Build vs. buy for filesystem/resource reactivity. If the roadmap includes any "react when something on disk changes" behavior — asset recompilation, config or translation hot-reload, cache invalidation, queue worker restarts, tenant-scoped config reloads — this package removes that from the custom-code column and turns it into a dependency decision.
- Developer-experience and local tooling investment. The v1.1.0 fluent API is a direct hit on integration cost: less boilerplate per watcher means faster prototyping of internal tooling (dev-time watchers, scaffolding generators, log tailers) and lower maintenance overhead for the team that owns them.
- Scope reduction for a watch/observe feature.
$listener->anything() collapses what is typically a per-event-type configuration matrix into a single catch-all registration. That is a concrete product win for features like "rebuild everything when any source file changes" or "invalidate the whole cache on any config edit," where the correct behavior is intentionally coarse.
- Stable callback contracts as an API decision. Listeners now receive the resource first and the absolute path second. That fixed signature is the contract your handlers code against — it determines how much glue code lives in your app versus the package, and whether you can standardize a shared handler base class across features.
- Upgrade timing on the roadmap. The release is explicitly backward compatible, so it can ride along with a routine dependency bump rather than occupying its own sprint slot. No migration or deprecation work is implied.
- Risk posture for production features. Watch-based behavior is genuinely useful in development and in controlled runtime contexts, but it is not a substitute for a real event bus. This release doesn't change that boundary, so it should not be used to justify replacing queue- or event-driven architecture on the roadmap.
When to Consider This Package
Consider adoption when:
- You have a concrete, bounded need to react to filesystem or resource changes — dev-time rebuilds, config/translation reload, cache busting — and the alternative is a bespoke, undertested watcher.
- Your team is already on Laravel/PHP and wants the watcher to compose with existing service providers, facades, and the container rather than standing up a separate Node/Chokidar or OS-level toolchain.
- You want a catch-all listener rather than fine-grained event taxonomy;
anything() is the right primitive when over-triggering is cheap and under-triggering is expensive.
- You value a fluent registration API for readability in application bootstrap code, and you expect multiple watchers with different scopes.
- You are willing to pin and track releases — a young package at v1.x is still settling its API, and this release's "should not break backwards compatibility" phrasing is a hedge worth noting.
Look elsewhere when:
- The requirement is high-throughput or multi-node production eventing. Filesystem watching is node-local, OS-dependent (inotify watch limits, polling fallback, container and network-mount quirks), and does not coordinate across instances. Use a queue, message broker, or platform-native event source instead.
- You need guaranteed delivery, ordering, or replay. Watching is best-effort by nature.
- The watched paths live on NFS, Docker bind mounts, or other layers where change notifications are unreliable — validate this before committing, because it is the most common way these features fail in practice.
- The use case is truly one-off. A few lines of
fs.watch or a cron-triggered checksum may be cheaper than owning a dependency and its upgrade cadence.
- You need a formal SLA, long-term support commitment, or security review the package cannot yet demonstrate at v1.1.
How to Pitch It (Stakeholders)
For executives: This is a small, low-risk dependency that lets us build "react when something changes" features — config reloads, cache invalidation, dev tooling — without writing and maintaining that plumbing ourselves. The new release makes it cheaper to integrate (a cleaner, more readable registration API) and more flexible (a single listener can now watch anything, and handlers get a consistent set of arguments). It is explicitly backward compatible, so adopting or upgrading costs us a routine dependency bump, not a migration project. It is an enabler for developer productivity and operational convenience, not a platform bet, and it does not change our production eventing strategy.
For engineering: v1.1.0 is a DX release. The fluent API reduces per-watcher boilerplate, anything() gives us a coarse catch-all without enumerating event types, and the callback signature is now stable at ($resource, $absolutePath) — standardize handler base classes against that now, since it's the contract we'll live with. The changelog says the release "should not" break backwards compatibility rather than guaranteeing it, and it also mentions test-level fixes, which suggests the suite is still maturing. Treat v1.1.0 as a routine bump, pin the version, and smoke-test our watchers on the target OS and mount type — inotify limits and container filesystem layers are where this class of tooling actually breaks. Budget the risk as low, but verify the environment rather than assuming the abstraction holds.