Watcher Laravel Package

Technical Evaluation

Architecture fit. hyperf/watcher is a development-time only utility. It runs an out-of-band process that watches configured source paths and restarts the Hyperf server when files change. It has no place in a request lifecycle, holds no business logic, and contributes nothing to a production runtime. Its architecture fit is therefore narrow and absolute: it fits only the Hyperf long-running Swoole/PHP-CLI process model, where there is no per-request bootstrap to pick up edits. That is precisely the gap it closes.

It does not fit the standard Laravel/PHP stack. Laravel under PHP-FPM gets reload-on-request for free; Laravel Octane already ships a watch mode (php artisan octane:start --watch), and frontend/asset hot reload is handled by Vite. For a Laravel-first organization, this package's architecture fit is zero unless the team runs Hyperf services alongside Laravel (common in mixed estates, where Hyperf handles high-concurrency/gRPC gateways and Laravel handles CRUD/admin surface).

Integration feasibility. High and cheap. It is a require-dev composer dependency plus a config/autoload/watcher.php path list, invoked via the Hyperf console (server:watch). No application code changes, no migrations, no public API surface to learn. Realistic TPM-level effort estimate: half a day for one platform engineer to pilot in a dev container, one to two days to standardize across a Hyperf service repo.

Technical risk. Low blast radius, but not low signal risk:

Key questions.

1. Do we actually operate Hyperf services, or is this being evaluated against a Laravel-only estate? If the latter, this is the wrong candidate and Octane/Vite already cover the need.
2. Who owns the pin? Is the maintainer set (Hyperf org) broad enough to survive a single contributor stepping away, and does our dependency policy accept an org-backed but low-adoption dev tool?
3. What is the version-compatibility contract with the Hyperf minor line we run, and does the package assert it?
4. Does our dev-container topology (bind mounts, remote dev, Kubernetes-based dev pods) preserve inotify fidelity?
5. What is the measurable payoff? Candidate metric: median edit-to-verified-change loop time, and dev-environment restart toil per engineer per week.

Integration Approach

Stack fit. Treat this as a Hyperf-ecosystem toolchain item, not a Laravel one. Positioning it inside a Laravel program as a "Laravel hot reload" solution would be a misclassification and should be rejected at intake. Where Hyperf exists in the estate, the fit is native: same PHP version constraint, same Swoole extension requirement, same config-autoload conventions as the rest of Hyperf.

Migration path. Strictly additive and reversible in one commit:

1. Add under require-dev only; add a CI check that fails if the package appears in production lockfile resolution.
2. Land the config file with an explicit, narrow watch list (.env, app/, config/, routes/) — explicitly excluding vendor/, runtime/, and generated caches to avoid restart storms.
3. Wire it into the existing dev entry script or compose dev profile so engineers do not need to learn a new command.
4. Document the "restart, don't hot-swap" mental model in onboarding material.

Rollback is deletion of one line; there is no data, schema, or contract debt.

Compatibility. Validate against the matrix the team actually runs before adoption: PHP minor, Hyperf minor, Swoole version, and the concrete dev environment (Docker Desktop vs native Linux vs remote container). Confirm the package's own constraint declares support for the Hyperf line in use rather than relying on a permissive constraint. Treat the anomalous release date as a prompt to audit tags and commit activity directly rather than trusting registry metadata.

Sequencing.

1. Discovery (week 1): confirm Hyperf footprint, collect baseline edit-to-verify timings on the slowest-iterating service.
2. Pilot (week 1–2): one service, one engineer, behind an opt-in dev script.
3. Evaluate (week 2–3): compare against the manual server:start restart loop on the same tasks; check for missed-change and mount-related failures.
4. Standardize or drop (week 3–4): if the loop-time delta is real, promote to all Hyperf service templates via scaffolding; if not, drop and revisit when Octane-style parity arrives upstream.
5. Do not sequence this ahead of higher-leverage platform work (CI time, test runtime, local dependency caching) without evidence it is the dominant developer-feedback bottleneck.

Operational Impact

Maintenance. Very low carrying cost in an absolute sense — a dev-only dependency that generates no deployment surface, no runtime telemetry, and no on-call signal. The real maintenance burden is dependency hygiene: an unpinned or stale watch tool silently drifting from the Hyperf minor version turns into confusing dev breakage. Assign ownership to the developer-platform function, not to a product team, and pin it.

Support. No vendor SLA, no commercial backing beyond Hyperf org stewardship, and a community small enough that an issue may go unanswered. That is acceptable for a dev tool and unacceptable for anything else. Mitigation is an internal fallback runbook: if the watcher misbehaves, fall back to the manual restart command, which is the pre-existing workflow. Nobody should be blocked.

Scaling. Scaling dimensions are atypical: it does not scale with traffic or data volume at all. It scales with headcount and service count — value grows linearly with the number of engineers doing iterative Hyperf work, and cost is a per-developer file watcher plus restart-induced CPU spikes on local machines. At a handful of Hyperf services this is a marginal productivity line item, not a platform investment. It is not a candidate for a platform budget line of its own; fold it into broader developer-experience spend.

Failure modes. Plan for these explicitly:

• Silent watcher miss (mount/inotify incompatibility) — the highest-cost failure because it mimics a code bug. Mitigation: a startup banner confirming watched paths, and a documented "touch a file and confirm restart" smoke check.
• Restart storms — saved-on-format or generated files triggering cascading restarts. Mitigation: narrow path allowlist, ignore caches and runtime/.
• Orphaned processes / port collisions — a killed watcher leaving a bound server port, causing confusing startup errors.
• State loss on save — interrupted in-flight work (websocket sessions, in-memory caches, local consumers). Must be a documented expectation, not a support ticket.
• Accidental production inclusion — the one truly severe mode. Mitigation: require-dev enforcement in CI and lockfile scanning.

Ramp-up. Effectively zero learning curve: one command, one config file. Budget under an hour for a competent PHP engineer, most of it spent internalizing the restart-don't-hot-swap behavior. The TPM-level effort is not training but justification and containment — proving the loop-time gain on a real service and preventing the dependency from leaking into production. Given 17 stars and zero dependents, the honest framing for a portfolio review is: a low-risk, low-leverage developer-convenience tool for Hyperf teams, mis-scoped if presented as a Laravel package, and worth adopting only where Hyperf is already a committed part of the stack.