somnambulist/api-client
Somnambulist API Client gives Laravel and PHP developers a structured, testable way to consume external HTTP APIs. Define requests, send them cleanly, handle responses consistently, and keep third-party integrations maintainable without scattering HTTP logic through your app.
Architecture fit. somnambulist/api-client is a thin abstraction layer intended to reduce boilerplate when building outbound API integrations — typically a base client class, request/response handling, and conventions for mapping endpoints to methods. For a Laravel/PHP product, this is only a meaningful fit if the roadmap includes several first-party integrations (payments, CRM, shipping, identity, internal service mesh) and the team wants a shared, consistent client foundation rather than ad-hoc Guzzle calls. Where Laravel already provides Illuminate\Support\Facades\Http and the ecosystem offers Saloon (a mature, Laravel-native API client framework), this package occupies a narrow niche. It is a "build the plumbing once" tool, not a feature enabler. Treat it as infrastructure, not product capability.
Integration feasibility. Composer-installable, MIT-licensed, and presumably PSR-oriented, so it should coexist with Laravel's container and HTTP stack. Feasibility is high on a technical level — the surface area is small and the integration is a single dependency plus adapter classes. The practical constraint is not effort but confidence: with 1 GitHub star, 0 dependents, and a near-zero opportunity score, there is no external validation that the abstractions match real-world API patterns or that the package survives modern PHP/Laravel versions. Integration is cheap to attempt and cheap to reverse, which is the main argument in its favor.
Technical risk. High, and concentrated in provenance rather than code quality. The dominant risks are: (1) bus factor of effectively one maintainer with no visible downstream community; (2) dependency drift — packages of this vintage often pin PSR-7/PSR-18 or HTTPlug-era transports that conflict with current Guzzle/Laravel constraints, and HTTPlug is deprecated; (3) unclear support for the concerns that actually matter in production integrations — authentication/token refresh, retry and backoff policy, rate limiting, pagination, idempotency keys, and structured error mapping; (4) no evidence of a security disclosure process or CI matrix across PHP versions; (5) silent failure modes if responses are coerced into domain objects without explicit status/error handling. The low score is a signal, not a verdict — but it means the burden of due diligence sits entirely with us.
Key questions.
Stack fit. The package should be evaluated as a peer to Saloon and Laravel's Http facade, not as a replacement for either. If our codebase already standardizes on Http:: with a repository/service pattern, adding a second client abstraction creates inconsistency for little gain. If we have a sprawl of hand-rolled Guzzle wrappers and want convergence, this package is a candidate — but only alongside the more established option. Decision rule: adopt only if it demonstrably reduces code in a real integration compared with Saloon, and only behind an internal interface.
Migration path. Do not migrate existing integrations. Greenfield-only, one integration, wrapped. Define an internal ApiClientInterface (or reuse our existing outbound-gateway contract) and implement it with this package. All application code depends on our interface, never on Somnambulist\... types. That wrapper is the exit ramp: if the package is abandoned or a version conflict appears, we swap the implementation without touching domain code. Budget the wrapper as a first-class deliverable, not glue.
Compatibility. Before any code, run a dependency-resolution spike in a scratch branch against the actual application lockfile — not a clean skeleton. Confirm PHP constraint, Laravel version constraint, PSR-7/17/18 versions, and any Guzzle major-version pin. Check for conflicts with packages that also pin PSR implementations (HTTP clients, mailers, queue transports, telemetry). Verify the license and copyright header permit our intended use (MIT does). Confirm the package autoloads cleanly under our Composer 2 setup and that PHPStan/Psalm at our configured level does not explode on its internals.
Sequencing.
Http-based implementation.Gate the decision on the pilot, not on the README. Do not sequence this ahead of any revenue-bearing work.
Maintenance. Assume we own it. With a single maintainer and no dependents, upstream fixes for PHP/Laravel upgrades may lag by months or never arrive. Plan for a vendored fork or a patch set in composer.json (repositories + a pinned commit) as the steady state, and record that decision in the ADR. The cost is not the initial install; it is the recurring tax of re-validating the fork at each PHP minor upgrade.
Support. Community-only, no SLA, no vendor relationship, no security advisory channel we can subscribe to. Internal ownership must be explicit: a named engineer, an on-call expectation if the integration is customer-facing, and a documented escalation path. If the integration touches payments or PII, the absence of a security process is disqualifying on its own — route it through a security review before pilot.
Scaling. The package is not the scaling bottleneck; the transport underneath it is. Connection reuse, pooling, timeouts, circuit breaking, and concurrency are determined by Guzzle/PSR-18 configuration, not by this library. Confirm it exposes (or at least does not obstruct) per-request timeout, retry-with-backoff, and rate-limit handling. Verify behavior under sustained load with a load test on the pilot integration — specifically whether responses are buffered and whether large payloads stream.
Failure modes. The realistic failure modes, ranked: (1) abandonment — no release compatible with the next Laravel major, forcing an emergency rewrite; (2) dependency conflict introduced by a transitive PSR/HTTPlug pin, blocking an unrelated upgrade; (3) error-handling gaps that surface as swallowed exceptions or untyped failures in production; (4) missing observability hooks (no way to inject middleware for tracing, metrics, or request IDs) leaving the integration opaque during incidents; (5) undocumented behavior around retries causing duplicate side effects on non-idempotent calls. Each needs a mitigation in the pilot: an interface boundary for (1) and (2), an explicit error taxonomy test for (3), transport-level middleware for (4), and idempotency keys for (5).
Ramp-up. Low. The API surface is small and the mental model is conventional, so a mid-level engineer should be productive in under a day — provided the wrapper, the error taxonomy, and one worked example are documented. The real ramp-up cost is institutional, not individual: the team must learn to treat the dependency as unmaintained and understand the fork/patch process. Budget half a day of documentation and an ADR. If the pilot cannot be justified against Saloon in those terms, the correct TPM call is to keep the internal interface and drop the dependency.
How can I help you explore Laravel packages today?