Client Integration Tests Laravel Package

Technical Evaluation

What the package actually is. php-http/client-integration-tests is not an application testing library. It is a black-box conformance suite for teams that implement or maintain a PSR-18 HTTP client (or a wrapper around one). It ships an IntegrationTestCase you subclass, a local test HTTP server (vendor/bin/http_test_server), per-adapter PHPUnit testsuites, and a custom result printer, then runs a broad battery of assertions covering redirects, auth, timeouts, streaming, header semantics, and optionally async transports. The README states the constraint plainly: "This package should not be used on its own."

That framing drives everything below. For a typical Laravel product team using Illuminate\Support\Facades\Http (Guzzle under the hood, already validated upstream), leverage is close to zero — there is no seam to plug into. The addressable audience is narrow: a platform team that authors an internal HTTP client abstraction, forks or pins an adapter, or is running a formal bake-off between client libraries.

Architecture fit — weak-to-moderate, conditional. Laravel's Http::fake() and Http::preventStrayRequests() cover application-level HTTP testing; php-http/mock-client covers unit-level mocking. This package occupies a different, much thinner layer: proving a client implementation speaks PSR-18 and PSR-7 correctly. The dependency is require-dev only — zero runtime footprint — which caps both the upside and the blast radius. The correct TPM posture is a conditional yes: approve only if we can name the client implementation we own. If we cannot, this is a no-op and the evaluation ends.

Integration feasibility — mechanically easy, operationally non-trivial. Composer install, one subclass, one testsuite entry, one CI job. But this is a network-and-process test suite, not a unit suite, and each of those properties is a workstream:

• It needs a local server process on a port (conventionally 8080) — a real constraint in containerized CI where port collisions and startup races are common.
• History shows external dependency churn: 3.1.1 reverted to httpbin.org. Anything hitting a public endpoint introduces egress, rate-limit, and availability failure modes outside our control.
• Async coverage requires ext-uv/ReactPHP and an optional HTTPlug 2.0 install; the practical answer is --exclude-group async, which reduces effective coverage below the headline.
• Version coupling to PHPUnit is tight. 4.0.0 targets "PHPUnit > 9," while modern Laravel has moved to PHPUnit 10/11 and Pest. Whether the 4.x test classes actually run cleanly on PHPUnit 10+ is an open question, not a documented guarantee.

Technical risk — low-to-moderate, and mostly supply-chain verification rather than runtime risk. Mitigants: MIT license, php-http is the legitimate HTTPlug organization, a changelog going back to 0.1.0, and a dev-only dependency that cannot reach production. Concerns:

• Adoption signal is very weak (16 stars, 0 listed dependents), which is odd given php-http adapters historically used this suite. I read that as metadata unreliability rather than absence of use — but it means we cannot use ecosystem size as a proxy for quality.
• The recorded last-release date (2026-07-05) is future-dated. That is a data-quality red flag in the scoring pipeline. It does not imply a malicious package, but it does mean treat these repository metrics as unverified; confirm the actual latest tag, commit history, and Packagist metadata before any approval or procurement decision.
• Maintenance is single-organization and effectively volunteer-driven. Bus factor is the real risk, not code quality. The mitigating fact for a TPM is that the package is small and MIT — worst case we can vendor the handful of test classes we actually exercise.

Key questions.

1. Do we own, fork, or wrap a PSR-18 client implementation anywhere in our stack? If no, stop here — this is the entire decision.
2. Is our target PHPUnit major (10/11) genuinely supported, or only nominally allowed by the constraint? This needs a timeboxed spike, not a docs read.
3. Which tests require egress to httpbin.org versus the bundled local server, and can we run 100% offline on the pinned version?
4. Who owns the CI job and the version pin? If nobody is named, this becomes an orphaned flaky job within two quarters.
5. Why are the release date future-dated and dependents zero — is this the canonical package or a mirror/fork? Confirm provenance before pinning.

Integration Approach

Stack fit — treat this as a platform-engineering tool, not an app-team dependency. Three legitimate uses:

• Conformance gating for an internal PSR-18 client or HTTP abstraction we author or fork.
• A formal evaluation scorecard when choosing between Guzzle, Symfony HttpClient, and curl-client — objective, standards-anchored, comparable across candidates in a way opinion is not.
• Regression gating on an adapter we pin, so upstream behavior changes surface as failing tests instead of production incidents.

It does not replace Http::fake(), Http::preventStrayRequests(), or contract tests against our own API consumers. State that boundary explicitly in the adoption RFC; otherwise expect scope creep into application test suites, where the package adds cost and no value.

Migration path — greenfield, additive, reversible.

1. composer require --dev php-http/client-integration-tests pinned to an exact minor, in the adapter package rather than the main application.
2. Create tests/Integration/<OurClient>IntegrationTest.php extending the provided base test case; implement createClient() and getOptions() so we exercise our configured stack (retries, logging, auth middleware), not a bare client.
3. Register a named testsuite in phpunit.xml mirroring the README's --testsuite curl pattern, and keep it out of the default run.
4. Wire the local test server into CI: start before, kill after, health-check the port, and fail the job if the server is unavailable rather than skipping.
5. Start with --exclude-group async; enable async only if we genuinely ship an async transport.

Compatibility — pin package and PHPUnit together. These test classes break on PHPUnit majors in ways discovered only at runtime. Budget an upgrade task whenever Laravel's PHPUnit major moves. Also verify PSR-17 factory availability (laminas/laminas-diactoros or nyholm/psr7): 4.0.0 replaced $messageFactory with $requestFactory/$streamFactory, which is a hard break for any subclass written against 3.x. Note also that 4.1.x allows guzzlehttp/psr7 v3 and relaxes the HEAD Content-Length expectation — pinning to the version whose semantics we accept matters more than pinning to "latest."

Sequencing.

• Step 0 — decision gate. Confirm we own a PSR-18 client. No owner, no project.
• Step 1 — spike, timeboxed to one engineer-day. Branch, throwaway subclass, pinned PHPUnit. Exit criteria: suite runs green offline with async excluded, on our actual PHPUnit major.
• Step 2 — go/no-go. If green, promote to a CI gate living in the adapter repo (not the app repo) with a named owner and an exact pin landed in the same PR. If red — PHPUnit incompatibility or unavoidable network dependency — stop. Fall back to a hand-rolled smoke test of roughly ten assertions on redirects, headers, and streaming. Do not sink days into patching a volunteer package we do not depend on.
• Step 3 — steady state. Re-evaluate only on PHPUnit majors or when we change adapters.
• Step 4 — optional. Add async coverage after a stable quarter, and only if async is shipped functionality.

Operational Impact

Maintenance. The dependency itself is static; the CI job is what rots. Upstream is single-org and volunteer-run, so expect long gaps between releases and little appetite for bespoke bug reports. Our steady-state cost is roughly 2–4 engineer-days per year, spiking to about a week in a PHPUnit-migration year. One real lever: the project has a contributing guide and accepts PRs, so we can fix our own breakages and upstream them rather than waiting.

Support. No vendor, no SLA. Channels are GitHub issues and the php-http docs site. The escalation path is to vendor the specific test classes we use — the codebase is small and MIT-licensed, so forking is a credible last resort rather than a rewrite. That is the single most important fact for a TPM sign-off: the exit cost is low.

Scaling. Fine as a narrow gate, poor as a general practice. Each client under test means one subclass, one testsuite, and one CI job with its own server process and port. Running this across many adapters multiplies CI minutes and server-management overhead for diminishing returns. Constrain it to clients we own — realistically zero or one. Its value is concentrated, not distributed.

Failure modes, ranked by likelihood.

1. Flaky CI from the local server — port collisions, startup races, zombie processes. Mitigate with a health check and fail-fast, never a skip.
2. Silent skip — the worst mode, because the job looks green while testing nothing. Assert an expected minimum test count, and treat skips as failures.
3. External egress to httpbin.org — rate limits and outages. Mitigate by pinning a version that uses the bundled server, or by running our own httpbin container.
4. PHPUnit major bump breaks the subclass at runtime — mitigate with a matrix entry that runs this job before the Laravel upgrade merges.
5. Orphaned job — owner leaves, job goes red for months, someone disables it. Assign an owner in the same PR that adds the pin.
6. False confidence — stakeholders assume it covers application HTTP behavior. It tests client implementation conformance, not our API calls. Socialize the boundary in the RFC.

Ramp-up. Low for an individual PHP developer: Composer plus a subclass plus a phpunit.xml entry is about half a day if the spike passes. The organizational prerequisite is conceptual, not mechanical — PSR-18/PSR-7/PSR-17 literacy, understanding which factory does what, why HEAD responses omit Content-Length, and why TRACE bodies are invalid per RFC 7231. Designate one engineer as HTTP-client owner; do not fan this out. Onboarding doc should be one page: how to run the server locally, the testsuite name, the pin policy, and the explicit statement of what this suite does not cover.