Api Dto Laravel Package

Product Decisions This Supports

• Control-plane features, not user-facing features. This package is the typed PHP contract for RoadRunner's gRPC API. It unlocks things like worker-pool introspection, health/readiness endpoints backed by real runtime state, and programmatic worker restarts. That's the difference between "we can observe our runtime" and "we guess."
• Zero-downtime deploy and hot-reload roadmap. Restart a single worker vs. resetting the whole pool, triggered from application code or a deploy hook, is a directly shippable reliability feature — and this is the plumbing for it.
• Build vs. buy on integration glue. Consuming generated DTOs (MIT, first-party to the RoadRunner org) is strictly cheaper than hand-rolling protobuf stubs and owning drift against upstream proto changes. Verdict: buy/consume, don't build.
• Autoscaling and capacity signals. If you're planning HPA-style behavior or cost-per-worker work, worker state exposed via RPC is a prerequisite input. This package is the cheap enablement step.
• Honest framing for prioritization: it's infrastructure, not differentiation. It creates zero product value on its own. Fund it as a small enabler inside an ops-tooling or reliability epic, not as a standalone initiative.
• New in v2.1.0 — a supply-chain decision, not a feature decision. The package was renamed from roadrunner-php/roadrunner-api-dto to roadrunner/api-dto. That is a dependency-identity change (composer name, and any lockfile, require line, CI install step, or SCA/inventory entry that references it). It changes how we consume the package, not what it does — but it must be captured in the epic's definition of done or we'll carry a stale reference.

When to Consider This Package

Adopt when:

• You run RoadRunner as your application server and have the gRPC/RPC API enabled (rpc.listen in .rr.yaml). Without that, the package is inert.
• You need programmatic control from PHP: pool status, worker restart, config-driven runtime behavior — typically for internal ops tooling or a small admin panel.
• You can pin the package and the RoadRunner binary to the same protocol generation and validate that coupling in CI. This remains the single biggest adoption criterion — and the v2.1.0 rename means that pinning rule now also applies to the package name: pick roadrunner/api-dto for new work and record the rename in the decision log rather than silently following whatever the lockfile resolves. Assume the v2.0.0-era name is a legacy alias at best; do not build new tooling against it.
• Your team is comfortable reading .proto files directly. The README refresh in v2.1.0 is a genuine but modest improvement — documentation and examples are still thin, and the API surface is still raw generated DTOs.

Look elsewhere or skip when:

• You're on php-fpm, FrankenPHP, or Swoole — zero value.
• You use RoadRunner purely as an HTTP server and never touch RPC — you don't need it.
• You want an ergonomic, higher-level SDK. This is raw generated DTOs; the developer experience lives in the CLI and framework integrations, not here.
• You require a dependency with broad community support. Nine stars and zero listed dependents means near-zero ecosystem signal: few examples, few Stack Overflow answers, and you own the debugging. The rename compounds this slightly — a package name change fragments whatever small trail of search results, blog posts, and examples already exists. That's acceptable for a narrow first-party utility and unacceptable if the surrounding team is junior or the release train is long.
• Protocol skew is structurally likely (multiple teams, slow binary upgrades). Then the versioning maintenance cost can quietly exceed the integration savings.

Risk note for the decision record: low adoption here is not a market-opportunity signal — the "opportunity" score reflects whitespace in a niche generated-code package, not unmet demand you can monetize. The rename shipping as a minor version bump (2.1.0) rather than a major signals the maintainers treat package identity as non-breaking — either a replace/alias is in place or the namespace is unchanged. Verify that assumption against our own composer resolution before planning work; if it holds, the migration is a lockfile-and-require edit, not a refactor. Treat the release cadence as evidence of active upstream tracking, not of stability guarantees.

How to Pitch It (Stakeholders)

For executives: A free, MIT-licensed, first-party component that lets our PHP application manage its own RoadRunner runtime — the foundation for real health checks, safer deploys, and eventually autoscaling. No license cost, no vendor lock-in, and it removes weeks of custom integration work. It won't win customers on its own; it's the cheap enabler under reliability and ops features we're already planning. The latest release renames the package; it's a one-line dependency change on our side, not a new integration, and it's a sign the upstream project is actively maintained.

For engineering: Generated DTOs plus the .proto definitions for RoadRunner's gRPC API — we get type safety and IDE support instead of hand-maintained stubs that drift. Two conditions: treat the package version as coupled to the RoadRunner binary and pin both, with a CI check that the protocol versions agree; and keep all usage behind a thin internal adapter so replacing it later is a one-file change. Action item from v2.1.0: install and reference roadrunner/api-dto (the roadrunner-php/roadrunner-api-dto name is legacy), update our composer.json, lockfile, and any SCA/allowlist entries, and confirm in CI that nothing still resolves the old name. Upstream adoption is low, so assume we own the support burden and budget accordingly. Scope it inside the ops-tooling epic as a day-or-two integration, not a project.