Watch Files Laravel Package

Technical Evaluation

Architecture fit. The package's core proposition — stateless file/directory change detection — is actually well-aligned with PHP's share-nothing execution model. Unlike inotify-based watchers, which require a long-lived daemon holding watch descriptors, a stateless snapshot/diff approach can be invoked from a scheduled command, a queue job, or a one-shot CLI call. That is the right shape for Laravel, where the request/console lifecycle is short and persistent processes are the exception (Horizon, Octane, Supervisor-managed workers). However, the package is a generic PHP library, not a Laravel package: there is no service provider, facade, config file, or publishable assets. Architectural fit is therefore "plausible primitive, not a solution."

Integration feasibility. Composer-installable and small surface area, but adoption signals are near-zero: 9 stars, 0 dependents, no evidence of production use. There is no visible test suite, CI badge, or release cadence to inspect, and no Laravel version constraints to validate against. Integration would require writing an adapter layer, a config surface, and our own tests — meaning we absorb the integration cost of a first-party package without getting first-party support.

Technical risk. High, concentrated in four areas:

• Abandonment/bus factor. Single-maintainer package with no downstream dependents. Any incompatibility with modern PHP (typed properties, deprecations, each()/dynamic property removals) becomes our problem.
• "Stateless" cost model. A stateless watcher must reconstruct or persist a prior snapshot, then compare. That implies an O(number of files) walk per invocation rather than O(number of changes). On large trees (vendor/, node_modules/, storage/) this is expensive and needs explicit exclusion.
• Detection fidelity. If it relies on mtime, it inherits sub-second granularity issues, clock skew on network filesystems, and missed changes during same-second writes. If it hashes, CPU cost rises sharply.
• Concurrency and partial writes. Files being written while scanned can yield torn reads or false negatives; two concurrent scanners can race on any persisted snapshot state.

Key questions.

1. Does it use ext-inotify, polling, or snapshot hashing — and is the "stateless" claim about no daemon, no in-memory state, or both?
2. What PHP versions and language features does it target? Is it compatible with PHP 8.2/8.3?
3. Where is snapshot state stored, and is it safe under concurrent invocations?
4. How does it handle symlinks, permission-denied paths, unreadable files, and very deep trees?
5. What is the license, and are we permitted to fork and vendor it internally?
6. Is mtime used, and at what granularity? Are renames and deletes detected distinctly from modify events?
7. What is the per-scan latency on a representative tree (e.g., 50k files) in our environment?

Integration Approach

Stack fit. Marginal as-is. It is a PHP primitive that would sit beneath a Laravel service boundary. The correct pattern is to define a narrow internal contract — e.g. FileChangeDetector::changesSince(Snapshot): ChangeSet — implement it once with this package, and keep at least one alternative implementation behind the same interface. Candidate alternatives: a Symfony Finder + xxh3/md5 manifest diff we control outright, spatie/file-watcher for local dev use, or an OS-level inotifywait/fswatch sidecar where a daemon is acceptable.

Migration path. Do not rewrite existing logic around this package. Introduce the interface first, back it with a naive in-house implementation to prove the contract, then evaluate crodas/watch-files as a swap-in behind the same interface. This keeps the decision reversible at near-zero cost and caps the blast radius if the package is abandoned mid-flight.

Compatibility. Validate against the PHP versions and Laravel LTS releases we actually run, in a throwaway branch: install, run the full test matrix, and explicitly check for deprecation notices under E_ALL. Inspect composer.json for open-ended constraints and transitive dependencies. Confirm behavior on our filesystem types — network mounts (NFS/EFS) frequently break both mtime semantics and inotify, so the storage backend matters as much as the code.

Sequencing.

1. Source audit (1–2 days): read the code, confirm mechanism, license, PHP support, state storage, and error handling.
2. Contract + baseline (2–3 days): define the internal interface; ship a trivial manifest-diff implementation and a test harness.
3. Proof of concept (3–5 days): wire crodas/watch-files behind the interface in a non-critical path — local dev tooling, cache warming, or an ingestion staging directory.
4. Shadow evaluation (1–2 weeks): run both implementations against the same tree, compare detected change sets, and measure scan latency and memory.
5. Decision gate: adopt (fork into our namespace), or replace with the in-house implementation. Set an explicit criterion up front — e.g. "must match baseline detection with < 5% false negatives and < 200 ms scan on a 10k-file tree."

Operational Impact

Maintenance. Assume we own the code from day one. With zero dependents and minimal community, there is no upstream to lean on for bug fixes or PHP version bumps. Budget for a fork under an internal namespace with our own CI, changelog, and deprecation policy. This is a reasonable cost for ~200 lines of file-scanning logic; it is not reasonable if the package turns out to have a large or opaque internals surface.

Support. No vendor, no SLA, no security advisory channel. Any CVE or PHP-incompatibility event is discovered by us. Mitigation: keep the dependency behind an interface so removal is a one-file change, and add a dependency-review step to the standard intake process.

Scaling. Cost scales with tree size per invocation, not with change volume — the opposite of what most teams expect. Practical controls: restrict scans to explicit allowlisted subtrees; hard-exclude vendor/, node_modules/, storage/framework, and log directories; tune poll interval against acceptable detection latency; prefer manifest hashing only on directories where mtime is unreliable; and never run the scan inside a request path. On a large monorepo this can be seconds per tick, which drives the scheduling design.

Failure modes.

• False negatives from mtime granularity, clock skew, or files rewritten within the same second — silently missed changes are the worst outcome.
• Torn reads on files being actively written, producing spurious or failed diffs.
• Permission errors aborting a whole scan rather than skipping the offending path.
• Symlink loops causing unbounded traversal or hangs.
• Snapshot corruption/races if two invocations overlap (e.g., a slow scan overlapping the next cron tick).
• Memory growth when building full manifests of large trees.
• Silent failure if the scheduled command swallows exceptions — no alert means changes quietly stop being detected. Each of these needs a corresponding guardrail: max-depth, per-path try/catch, invocation locking, explicit failure alerting, and a heartbeat metric proving scans are still running.

Ramp-up. Low conceptual overhead — the API is small and the file-watching mental model is familiar to most engineers. The real ramp-up cost is in operational understanding: why mtime is not a reliable signal, how atomic renames appear to a scanner, and why the scan cost profile differs from inotify. Plan for roughly a day of team onboarding plus the shadow-evaluation period before anyone trusts the output.