Watcher Laravel Package

Product Decisions This Supports

• Developer inner-loop investment (DX budget): This is not a customer-facing capability. It is a cost-of-delivery lever. It shortens the edit → reload → verify cycle for every backend engineer working on a Hyperf service, which compounds across sprints. Frame it in roadmap terms as engineering throughput, not as a feature.
• Framework selection / ecosystem completeness: If Hyperf is a candidate runtime, a maintained first-party hot-reload watcher is a checkmark in the "does the ecosystem cover the day-to-day?" column. Its presence lowers the perceived switching cost from Laravel or a plain Swoole setup.
• Standardizing local development: Supports a decision to define one blessed local dev workflow (make dev, a Composer script, a container entrypoint) rather than letting each engineer improvise with while true; do ...; done loops or manual restarts.
• Containerized / remote dev environments: Useful where engineers do not run PHP natively — devcontainers, Docker Compose, or remote workspaces — because restarting the server is the only practical reload mechanism for a long-running coroutine runtime.
• Build vs. buy (build vs. adopt): The alternative is a 50-line shell loop or an in-house watcher. Adopting is cheaper than building, but the low adoption signal (17 stars, 0 dependents) means the real comparison is "adopt a thin dependency" vs. "own ten lines of script". Neither is a strategic commitment.
• Onboarding and demo velocity: Shortens time-to-first-meaningful-change for new hires and makes live demos and spike work less fiddly.
• Explicitly NOT supported: Any production, staging, or performance-sensitive decision. Watchers are dev-only by definition and must never be in a runtime image.

When to Consider This Package

Adopt (as a dev-only dependency) when:

• The service is genuinely Hyperf-based and runs on Swoole/Swow, where the process must be restarted to pick up code changes.
• You have two or more engineers, or one engineer iterating frequently — the payoff is per-edit, so it scales with change volume.
• Local dev is containerized or otherwise not trivially restartable by hand.
• You are willing to pin an exact version in require-dev and treat upgrades as routine maintenance rather than a guarantee.
• You accept that the fallback (a file-watch shell script or Swoole's own reload) is a half-day of work, so the downside of the dependency failing is bounded.

Look elsewhere or skip when:

• Production or any shared environment. Non-negotiable: dev-only.
• Non-Hyperf stacks. Laravel, Symfony + RoadRunner/FrankenPHP, or plain PHP-FPM have their own established answers; do not force this in.
• You need battle-tested, widely-adopted tooling. 17 stars and zero dependents is thin evidence. There is no meaningful base of public bug reports, and single-maintainer risk is real even under the Hyperf org umbrella. Verify the release cadence actually tracks Hyperf framework releases before relying on it.
• Very large monorepos or heavy vendor trees. Naive file watchers can burn CPU or hit inotify limits on Linux and fall back to polling on macOS/Windows. Benchmark on a real repo before standardizing.
• Frontend assets are the bottleneck. This watches PHP; it does nothing for JS/CSS HMR. Do not let it be sold as a general hot-reload story.
• Your platform team already owns a dev-runner. Duplicating watchers across a toolchain creates two sources of truth about how the app starts.

How to Pitch It (Stakeholders)

For executives (one paragraph): This is a small, dev-only tool that automatically restarts the application server when code changes, so engineers do not have to stop and restart it manually hundreds of times a week. It ships nothing to customers, carries no production risk, and costs effectively nothing to adopt — it is a require-dev line and a script alias. The return is measured in saved minutes per engineer per day, plus faster onboarding. The risk is equally small: it is maintained under the Hyperf project, and if it ever stalls we fall back to a short internal script. Recommendation: adopt as a pinned dev-only dependency; do not put it on the roadmap as a deliverable, and do not let any release process depend on it.

For engineering leads: Add it to require-dev, pin the version, and wrap it behind a single documented command so nobody hand-rolls their own watcher. Document the escape hatch — a shell file-watch loop or the runtime's native reload — in the README so the team is never blocked if the package lags a Hyperf upgrade. Benchmark it once on the largest repo you have; if watch overhead is noticeable, scope it to app/ and config/ rather than the project root. Do not add it to production images, CI test jobs, or deployment pipelines.

The decision being asked for: a yes on a low-cost, reversible, dev-only tooling addition — with a named owner, a pinned version, and a documented fallback. If any of those three cannot be assigned, the honest answer is to keep the shell-loop workaround and revisit later.