Streams

Guzzle uses PSR-7 stream objects to represent request and response message bodies. These stream objects allow you to work with various types of data all using a common interface.

HTTP messages consist of a start-line, headers, and a body. The body of an HTTP message can be very small or extremely large. Attempting to represent the body of a message as a string can easily consume more memory than intended because the body must be stored completely in memory. Attempting to store the body of a request or response in memory would preclude the use of that implementation from being able to work with large message bodies. The StreamInterface is used in order to hide the implementation details of where a stream of data is read from or written to.

The PSR-7 Psr\Http\Message\StreamInterface exposes several methods that enable streams to be read from, written to, and traversed effectively.

Streams expose their capabilities using three methods: isReadable(), isWritable(), and isSeekable(). These methods can be used by stream collaborators to determine if a stream is capable of their requirements.

Each stream instance has various capabilities: they can be read-only, write-only, read-write, allow arbitrary random access (seeking forwards or backwards to any location), or only allow sequential access (for example in the case of a socket or pipe).

Guzzle uses the guzzlehttp/psr7 package to provide stream support. More information on using streams, creating streams, converting streams to PHP stream resource, and stream decorators can be found in the Guzzle PSR-7 documentation.

Creating Streams

The best way to create a stream is using the GuzzleHttp\Psr7\stream_for function. This function accepts strings, resources returned from fopen(), an object that implements __toString(), iterators, callables, and instances of Psr\Http\Message\StreamInterface.

  1. use GuzzleHttp\Psr7;
  3. $stream = Psr7\stream_for('string data');
  4. echo $stream;
  5. // string data
  6. echo $stream->read(3);
  7. // str
  8. echo $stream->getContents();
  9. // ing data
  10. var_export($stream->eof());
  11. // true
  12. var_export($stream->tell());
  13. // 11

You can create streams from iterators. The iterator can yield any number of bytes per iteration. Any excess bytes returned by the iterator that were not requested by a stream consumer will be buffered until a subsequent read.

  1. use GuzzleHttp\Psr7;
  3. $generator = function ($bytes) {
  4.     for ($i = 0; $i < $bytes; $i++) {
  5.         yield '.';
  6.     }
  7. };
  9. $iter = $generator(1024);
  10. $stream = Psr7\stream_for($iter);
  11. echo $stream->read(3); // ...

Metadata

Streams expose stream metadata through the getMetadata() method. This method provides the data you would retrieve when calling PHP’s stream_get_meta_data() function, and can optionally expose other custom data.

  1. use GuzzleHttp\Psr7;
  3. $resource = fopen('/path/to/file', 'r');
  4. $stream = Psr7\stream_for($resource);
  5. echo $stream->getMetadata('uri');
  6. // /path/to/file
  7. var_export($stream->isReadable());
  8. // true
  9. var_export($stream->isWritable());
  10. // false
  11. var_export($stream->isSeekable());
  12. // true

Stream Decorators

Adding custom functionality to streams is very simple with stream decorators. Guzzle provides several built-in decorators that provide additional stream functionality.