Psr7 Integration Tests Laravel Package

Getting Started

Begin by requiring the package in your test environment:

composer require --dev php-http/psr7-integration-tests

If you are using PHPUnit 13, require version 1.5.2 or newer; earlier releases may conflict with PHPUnit 13 during Composer resolution.

Then, in your phpunit.xml, include the test suite and create a minimal test class that extends Http\Tests\Integration\Psr7IntegrationTestCase. The class must implement a createMessageFactory() method returning your PSR-7 message factory (e.g., Symfony HttpClient, Nyholm/psr7, Guzzle). Run tests via phpunit --testsuite=psr7-integration.

First use case: Validate a new or custom PSR-7 implementation (e.g., MyProject\Psr7\Factory) before publishing it — run integration tests to catch deviations from PSR-7 standards in common operations like withHeader(), stream buffering, or URI mutation.

Implementation Patterns

• Inherit and configure: Extend Psr7IntegrationTestCase, implement required factory methods, and optionally override setUp() to configure environment-specific behavior (e.g., mock file system for stream tests).
• Custom test traits: Wrap the integration suite in your own trait (e.g., HasPsr7Compliance) to reuse across multiple packages (e.g., HTTP clients, middleware libraries).
• CI automation: Add to CI workflows to run against different PSR-7 implementations (e.g., via environment variables or parallel jobs) to catch cross-implementation bugs. With PHPUnit 13 support added in 1.5.2, include PHPUnit versions in your CI matrix if you support multiple major PHPUnit releases.
• Hybrid factories: When using polyfills (e.g., php-http/discovery), run integration tests against the resolved factory to verify runtime behavior, not just compile-time interfaces.

Gotchas and Tips

• PHPUnit version constraints: PHPUnit 13 installation requires php-http/psr7-integration-tests 1.5.2+. If Composer reports a conflict, check the locked package version before changing your PHPUnit constraint.
• Immutability trips: PSR-7 mandates immutability — tests will fail if with*() methods mutate the original object. If tests break, inspect return values and reference identity.
• Stream edge cases: Tests involving fopen('php://temp', 'r+') or large buffers may fail in environments with limited memory limits — adjust memory_limit for full coverage.
• Missing factory contract: Ensure your factory implements both MessageFactoryInterface and StreamFactoryInterface — the suite validates both.
• Namespace collisions: Avoid class name conflicts by using a dedicated Tests\Integration\ namespace; IDE autocomplete may misfire if tests are added at root level.
• Extensibility: Override provide*Data() methods in your subclass to add custom edge cases (e.g., non-standard headers, malformed URIs), while retaining core compliance checks.
• Test feedback: The suite throws descriptive exceptions — use --debug with PHPUnit to trace failures back to exact immutability or type violations.