Etcd Discovery Laravel Package

Product Decisions This Supports

• Monolith-to-service-split sequencing. Whether to carve a PHP application into independently deployable services hinges on whether those services can find each other at runtime without hardcoded host lists. This package is the piece that makes dynamic addressing possible for Workerman-based PHP services on an etcd backbone — so it is a gating dependency for a services roadmap, not a standalone feature.

• Build vs. buy on service discovery. The alternative is hand-rolling a registry (a database table of hosts plus a cron sweeper plus a client-side poller) — typically 2–4 engineer-weeks plus permanent on-call exposure for a component nobody owns. Adopting this package reframes the decision from "build a registry" to "operate etcd," which is a far more standard competency.

• Runtime and transport standardization. ETCD-based registration effectively preselects a long-running process model (Workerman/Swoole/webman/Octane) and points toward RPC-style transports (gRPC, JSON-RPC over TCP) rather than HTTP-per-request FPM. That is a multi-quarter architectural commitment and should be made deliberately, with this package as the concrete proof point in the design doc.

• Rollout strategy features. Registry metadata is the natural carrier for weighted routing, blue/green cutover, and canary percentages without a service mesh. If the roadmap contains progressive delivery, this belongs in the "enabling infrastructure" line item rather than being deferred behind a gateway project.

• Deployment and reliability OKRs. Graceful shutdown, lease TTL, and health-check semantics directly set achievable targets for "zero-downtime deploys" and "no 502s during scale events." The package's lease/deregistration behavior determines whether those OKRs are realistic or aspirational.

• Vendor and platform choice. If the org is evaluating Nacos, Consul, or Kubernetes-native discovery, a working PHP client for etcd is a data point in that comparison — it removes "no viable PHP story" as an argument against etcd.

• Use cases worth validating first: internal service-to-service calls between Workerman workers, gRPC-PHP backends, multi-tenant routing keyed on registry metadata, and sidecar-free environments (bare metal, VMs, Docker Compose) where Kubernetes DNS is unavailable.

When to Consider This Package

Adopt-pilot criteria:

• You already run etcd, or will run it for config/coordination regardless — the marginal cost of using it for discovery is near zero.
• Services run as persistent processes (Workerman, Swoole, webman, Octane). Standard PHP-FPM is a poor fit: the register-lease-deregister lifecycle assumes a long-lived process, and per-request registration would be pathological.
• You are outside a Kubernetes cluster, or inside one but deliberately bypassing cluster-native Service discovery (e.g., cross-cluster, hybrid cloud, or latency-sensitive RPC that wants client-side load balancing).
• You need client-side load balancing or instance-level metadata that ClusterIP Services cannot express.
• You can absorb the maintenance risk: 10 stars, zero dependents, and a single maintainer mean you must be prepared to fork and own the code. Budget for reading the source before shipping it, and wrap it behind an internal ServiceRegistry interface so it is replaceable.

Look elsewhere when:

• You are a single deployable application. Static configuration is cheaper and more debuggable; discovery is solving a problem you do not yet have.
• You are all-in on Kubernetes and are content with Services plus an Ingress/Envoy. kube-proxy and CoreDNS already do this, with a support model this package cannot match.
• You need a mature, well-documented polyglot control plane with health checking, UI, ACLs, and commercial support — Consul or Nacos are the better comparison points, and their PHP clients, while imperfect, come with organizational backing.
• The team has no etcd operational experience and no appetite to acquire it. etcd is small but unforgiving (quorum, compaction, watch storms); a registry with no operator is worse than a static list.
• You require SLA-backed support, published security response, or a dependency your compliance process will accept. Ten stars and no dependents will fail most vendor-risk questionnaires.
• Latency budget is extremely tight and the extra hop to etcd on a watch reconnect path is unacceptable without caching — in which case you are building a caching layer anyway and should evaluate a lighter embedded approach.

How to Pitch It (Stakeholders)

To executives: This is small, unglamorous plumbing that unlocks something larger. It lets PHP services announce themselves and find each other automatically, which is what makes horizontal scaling, zero-downtime deploys, and independent team releases possible without hand-maintained server lists. The strategic value is optionality: it commits us to a well-understood open-source coordination system (etcd) instead of a bespoke registry we would own forever. The caveat is candid: this library is a young, single-maintainer open-source project with essentially no adoption. I am not recommending we depend on it as-is — I am recommending a time-boxed spike to validate the approach, with the understanding that we may adopt the pattern and vendor or fork the code. Cost is measured in days, not quarters; the risk is contained and the architectural payoff is real.

To engineering: Treat this as a reference implementation and a shape for the design, not a finished dependency. It demonstrates the etcd lease-register-keepalive-deregister loop inside a Workerman event loop, which is the part everyone gets wrong. Before committing, we should audit: etcd API version compatibility (v3 leases and watches, not v2), reconnect and watch-resubscribe behavior under etcd leader election, behavior when the event loop blocks, graceful-shutdown deregistration timing versus in-flight requests, and whether the client dependency is maintained. My recommendation is to pin it, wrap it behind our own registry interface with a static-config fallback, and assume we own the code within two quarters. If the spike shows the internals are thin, we fork — the surface area is small enough that owning it is cheaper than the integration risk of depending on it.