Php Sdk Laravel Package

Product Decisions This Supports

• Build vs. buy for a public SDK surface. If "ship a PHP client for our API" is a roadmap item under developer experience, this package is the scaffold decision — not the product decision. It supplies the connector → resource → request → response → DTO layering (the boring, undifferentiating architecture) so sprints go to endpoint coverage, auth, docs, and error semantics instead of reinventing SDK structure. Plausible saving: one to two sprints of undifferentiated work at zero license cost.
• Developer experience as a distribution lever. If third-party integrators (marketplaces, agencies, ISV partners) are a growth channel, the SDK is the front door. Standardizing on one pattern lets us promise consistent ergonomics — same resource naming, same auth handling, same error shape — across every PHP integration we publish, and lets us document one mental model once rather than per-integration.
• Multi-SDK roadmap sequencing. The abstraction is deliberately framework-agnostic PHP, not Laravel-coupled. Choosing it sets a precedent that the "PHP" slot on the roadmap covers Symfony, Slim, and plain-PHP consumers without a second build effort — a scoping decision made once and inherited thereafter. If our audience is Laravel-only, this is the wrong shelf: the framework's HTTP client already covers that ground.
• Internal client standardization. The same primitives work for service-to-service HTTP clients and CLI tooling. Framing adoption as "one pattern, many consumers" turns a single integration decision into a reusable asset across partner SDKs, internal wrappers, and tooling.
• Scope discipline as a planning input, not a complaint. The package intentionally omits OpenAPI codegen, auth flows, and retry/backoff middleware. That is a roadmap input: those become our line items, with owners and estimates, to be staffed explicitly rather than assumed to arrive with the dependency. Budgeting them honestly is the difference between a two-week SDK and a two-month one.
• Vendor-risk budgeting as a first-class decision. Roughly 215 stars, one primary maintainer, zero dependent packages, and a 3.0.0 release whose entire changelog is a single line. The question is not "is this good code?" but "what is our exit cost, and what will the next upgrade cost?" Because the surface is small and MIT-licensed, the answer is favorable: vendor it, pin an inspected commit, and treat it as first-party code. That converts dependency risk into a scheduled half-day.
• Licensing and redistribution hygiene. MIT with no attribution or commercial friction means the SDK we publish to customers carries no legal review cycle. For a PM, that removes a gate from the release path.

What this package is not going to decide for you: it is not a code generator, not an auth solution, and not a retry/rate-limit strategy. Treat those as explicit deliverables in the plan, owned by named engineers, and the decision stays clean.

When to Consider This Package

Consider it when:

• The roadmap contains a PHP SDK for our own HTTP API, and the realistic alternative is weeks of hand-rolled scaffolding we would have to design anyway.
• The team is small, PHP-fluent, and time-to-first-working-SDK is the metric that matters.
• The artifact must be framework-agnostic — it has to run outside Laravel, and we do not want Laravel's HTTP client baked in as a hard dependency of a published package.
• The surface is modest and stable: one to two dozen endpoints, predictable payloads, no streaming, no websockets, no complex pagination gymnastics.
• We are willing to own the code — vendoring, patching, and reading a small MIT library is within our capability, including diffing v2.2.0 → 3.0.0 before adopting.
• We need a public, redistributable artifact and MIT licensing removes legal friction.

Look elsewhere when:

• We want an SDK generated from an OpenAPI spec. Use a generator and treat the output as the artifact; hand-rolled abstraction is not the value here.
• The integration is internal-only. Laravel's Http:: client wins outright: Http::fake() for tests, ->retry(), Http::pool(), Telescope capture. Adopting this package buys portability we would never exercise.
• The API surface includes OAuth flows, signed webhooks, streaming, or spec-driven contracts. That is Saloon territory for HTTP concerns, or a generator for spec fidelity — either way, our resource layer is written in-house.
• We need a supported vendor with a roadmap and SLAs. Single-maintainer, zero-dependents projects do not provide them, and no amount of good code changes that.
• The team is not prepared to staff the gaps — retries, backoff, token refresh, error mapping, and pagination are ours to build, and bolting them on post-launch is materially harder than doing them in the spike.
• Bus factor 1 is disqualifying for the release you are shipping. Mitigation exists (vendor or fork with a named internal owner, keep DTOs and resource layers free of SDK base classes in public signatures), but it requires an explicit decision and a budget line.

How to Pitch It (Stakeholders)

The one-liner: a small, MIT-licensed PHP scaffold that gives us the uninteresting parts of an SDK — transport, request building, typed responses, error handling — so the team spends its time on our API and our developers' experience, not on SDK architecture. Cost: zero license, one to two sprints of work saved, plus a half-day of diligence.

For executives: this is a buy-versus-build decision with a favorable risk profile. The artifact we publish is MIT and legally unencumbered, so no review cycle gates the release. The dependency is small enough to vendor and own outright, which converts "single-maintainer risk" from an open question into a scheduled half-day. The saving is real but bounded: it removes scaffolding work, it does not remove the work of shipping an SDK. The decision to make is whether a PHP SDK is on the roadmap at all — if the answer is no, the correct move is to decline this and move on.

For engineering: the package gives us the layer cake and stops. We own retries with jittered backoff, Retry-After handling, idempotency keys on retrying writes, token refresh via an injectable provider, response hydration into our own DTOs, and centralised error mapping at the client boundary. Testing happens at the PSR-18 transport boundary, not through Http::fake() — budget the first week for that harness. Pin the exact version, read src before writing a subclass, and read the v2.2.0 → 3.0.0 diff, because there is no upgrade guide. Keep SDK base classes out of public constructor signatures so the exit is a swap, not a rewrite.

The risks, stated plainly and mitigated:

• Single maintainer, zero dependents, undocumented major. Mitigation: vendor or fork with a named internal owner; pin and upgrade deliberately; record diff findings in our own changelog (~half a day per major).
• Gaps become our backlog. Mitigation: name owners and estimates for retries, auth refresh, pagination, and error mapping in the adoption plan itself.
• Onboarding cost is entirely internal. Mitigation: write internal docs in the same sprint as the build, not after — there is no Stack Overflow trail for this codebase.

The ask: approve adoption for the public PHP SDK track only, contingent on a two-day spike that builds one authenticated GET end to end and proves the test harness works. If the spike is clean, the follow-on is a scoped SDK plan with the gaps budgeted and a named owner for the vendored copy. If the spike surfaces friction, we drop the dependency and keep the resource layer design — the cost of finding out is two days.