Psr7 Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require guzzlehttp/psr7
   

   Ensure your composer.json specifies "guzzlehttp/psr7": "^3.2" (3.2.0 contains important stream-integrity fixes — see Gotchas).

2. First Use Case: Create a basic HTTP request/response using PSR-7 interfaces:

   use GuzzleHttp\Psr7\Request;
   use GuzzleHttp\Psr7\Response;
   
   // Create a request
   $request = new Request('GET', 'https://api.example.com/data');
   
   // Create a response (simulated)
   $response = new Response(200, [], '{"status": "success"}');
   
   // Use with a client (e.g., Guzzle HTTP client)
   $client = new \GuzzleHttp\Client();
   $result = $client->send($request);
   

3. Key Classes to Know:

   • Request, Response: Core HTTP message implementations.
   • StreamInterface: PSR-7 stream abstraction (e.g., AppendStream, BufferStream).
   • Utils: Helper methods for common tasks (e.g., streamFor(), copyToString()).
   • InflateStream / AppendStream: Decoding and concatenation decorators with tightened error semantics in 3.2.0.

4. Where to Look First:

   • PSR-7 Specification for interface contracts.
   • GuzzleHttp\Psr7\Utils for utility functions.
   • Stream decorators (e.g., AppendStream, LimitStream) for advanced use cases.
   • The 3.2.0 changelog entries for InflateStream and AppendStream if you already depend on either.

Implementation Patterns

Core Workflows

1. HTTP Message Handling

• Request/Response Creation:

  $request = new Request('POST', '/upload', [
      'Content-Type' => 'application/json',
  ], json_encode(['file' => 'data.bin']));
  

• Modifying Messages: Use Utils::modifyRequest() to avoid cloning:

  $modified = Utils::modifyRequest($request, [
      'set_headers' => ['Authorization' => 'Bearer token123'],
      'body' => Utils::streamFor('new-data'),
  ]);
  

2. Stream Manipulation

• Composing Streams: Combine multiple streams (e.g., file + in-memory data):

  $fileStream = Utils::streamFor(fopen('large_file.bin', 'r'));
  $appendStream = new AppendStream([$fileStream, Utils::streamFor('extra-data')]);
  

• Chunked Uploads: Use LimitStream to split large files:

  $original = Utils::streamFor(fopen('huge_file.bin', 'r'));
  $chunk = new LimitStream($original, 5 * 1024 * 1024, 0); // 5MB chunks
  

• Resumable Appends (3.2.0): When a read inside AppendStream times out, bytes already delivered from the current source are preserved. Resume from the offset already consumed instead of restarting the whole append chain:

  $append = new AppendStream([$partA, $partB]);
  $buffer = '';
  while (!$append->eof()) {
      $chunk = $append->read(8192); // a timeout throw no longer loses earlier bytes
      $buffer .= $chunk;
  }
  

3. Query String Handling

• Parsing/Building:

  $query = Query::parse('foo=bar&baz[]=1&baz[]=2');
  // ['foo' => 'bar', 'baz' => ['1', '2']]
  
  $built = Query::build(['foo' => 'bar', 'baz' => [1, 2]]);
  // 'foo=bar&baz=1&baz=2'
  

4. Stream Decorators

• Custom Logic: Extend streams with StreamDecoratorTrait:

  class LoggingStream implements StreamInterface {
      use StreamDecoratorTrait;
      public function read($length) {
          $data = $this->stream->read($length);
          logger()->debug("Read {$length} bytes: " . substr($data, 0, 20));
          return $data;
      }
  }
  

• Decoding Compressed Payloads:

  $decoded = new InflateStream($response->getBody());
  $json = Utils::copyToString($decoded); // throws on a source read failure in 3.2+
  

5. Integration with Guzzle HTTP Client

• Async Requests:

  $promise = $client->sendAsync($request);
  $promise->then(function (Response $response) {
      $body = Utils::copyToString($response->getBody());
  });
  

Integration Tips

1. Leverage Utils for Common Tasks:

   • Convert resources to streams: Utils::streamFor($resource).
   • Copy streams efficiently: Utils::copyToStream($source, $dest).

2. Handle Large Data:

   • Use BufferStream to control memory usage:

     $buffered = new BufferStream(1024); // 1KB buffer
     

3. Debugging Streams:

   • Use CachingStream for non-seekable streams (e.g., HTTP redirects):

     $stream = new CachingStream($nonSeekableStream);
     

4. Multipart Uploads:

   • Combine streams for multipart/form-data:

     $multipart = new MultipartStream([
         ['name' => 'file', 'contents' => $fileStream],
         ['name' => 'description', 'contents' => 'Uploaded via API'],
     ]);
     

5. Testing:

   • Mock streams with FnStream for unit tests:

     $mockStream = FnStream::decorate($stream, [
         'read' => function () { return 'mocked-data'; },
     ]);
     

6. Wrap Decoders in Error Handling (3.2.0):

   • InflateStream now surfaces source read failures that occur after decoded bytes were already produced. Wrap decompression in try/catch and treat a partial body as fatal rather than silently truncated:

     try {
         $body = Utils::copyToString(new InflateStream($encoded));
     } catch (\RuntimeException $e) {
         report($e); // do not persist the partially decoded payload
     }
     

7. Pin ^3.2 in Long-Running Workers:

   • Queue workers and streamed downloads benefit most from the AppendStream timeout fix; older 3.x releases can silently drop bytes mid-chain.

Gotchas and Tips

Pitfalls

1. Stream Ownership:

   • PSR-7 streams are not PHP resources. Closing a PHP resource (e.g., fclose()) does not close the stream. Use StreamInterface::close() explicitly.
   • Fix: Always call $stream->close() when done.

2. Seekable vs. Non-Seekable Streams:

   • Some streams (e.g., PumpStream, FnStream) may not support seeking. Check isSeekable() before calling seek().
   • Fix: Use CachingStream to wrap non-seekable streams if seeking is required.

3. Memory Leaks:

   • BufferStream and CachingStream buffer data in memory. Monitor memory usage for large streams.
   • Fix: Set appropriate buffer sizes (e.g., BufferStream(1024)).

4. Query String Parsing:

   • Query::parse() does not handle nested arrays (e.g., foo[a]=1&foo[b]=2 becomes ['foo[a]' => '1'], not ['foo' => ['a' => '1']]).
   • Fix: Pre-process nested data or use a custom parser.

5. Stream Decorator Order:

   • Decorators are applied from outer to inner. The outermost decorator is the first to receive calls.
   • Example:

     $stream = new LimitStream(new LoggingStream($originalStream));
     // LoggingStream is inner; LimitStream is outer.
     

6. UTF-8 Headers:

   • Headers must be UTF-8 encoded. Non-UTF-8 values may cause issues.
   • Fix: Use mb_convert_encoding() if needed.

7. Deprecated Methods:

   • Header::normalize() is deprecated. Use Header::splitList() instead.

8. InflateStream Now Fails Loudly (3.2.0):

   • Previously, a source read failure occurring after some decoded bytes were emitted could be swallowed, yielding a truncated payload that looked valid. Now the failure propagates.
   • Fix: Don't assume Utils::copyToString(new InflateStream($s)) returns a complete body — catch exceptions and validate checksums/lengths before use. Also check getMetadata('uncompressed_size') where available.

9. AppendStream Timeout Behaviour Changed (3.2.0):

   • A timeout mid-read no longer discards the bytes already read from the current source. If you wrote retry loops that assumed a full re-read from the start of the failing source, you may now double-append data.
   • Fix: Track consumed offsets ($stream->tell() on seekable parts) and resume from those offsets rather than restarting the whole AppendStream.

10. Upgrade Order for Nested Decorators:

    • When both InflateStream and AppendStream are in the chain, upgrade and re-test together: the two fixes interact (partial append + decoding failure).

Debugging Tips

1. Inspect Stream Contents:

   • Use Utils::copyToString($stream) to dump stream contents (be cautious with large streams).

2. Check Stream Metadata:

   • Access metadata via $stream->getMetadata() to debug issues (e.g., buffer sizes, seekability).

3. Enable Guzzle Debugging:

   • Add debug middleware to log requests/responses:

     $client->getConfig(['debug' => fopen('debug.log', 'w')]);
     

4. Validate PSR-7 Compliance:

   • Use tools like PHPStan with PSR-7 rules to catch interface violations early.

5. Reproduce Truncation Reports:

   • If you're chasing a "body cut short" bug, confirm the installed version with composer show guzzlehttp/psr7; anything below 3.2.0 can exhibit the InflateStream silent-truncation and AppendStream byte-loss behaviour.

Extension Points

1. Custom Stream Decorators:

   • Extend StreamDecoratorTrait for reusable stream logic (e.g., compression, encryption). Ensure your read() propagates failures instead of returning '', matching the 3.2.0 decoder semantics.

2. Stream Wrappers:

   • Use StreamWrapper::getResource() to integrate with PHP's stream functions (e.g., fopen(), fread()).

3. Message Parsing:

   • Override Message::parseRequest() or Message::parseResponse() for custom message formats.

4. Query String Customization:

   • Extend Query::build() or Query::parse() for domain-specific query handling.

5. Event-Driven Streams:

   • Combine PumpStream with callbacks for event-driven processing:

     $pumpStream = new PumpStream(function ($length) {
         return $generator->current() ?: false;
     });
     

6. Resilient Source Streams:

   • Implement retry/backoff inside your own source StreamInterface so that AppendStream and InflateStream never see a raw timeout — they now treat such failures as hard errors rather than truncation points.