itflow/libs/vendor/guzzlehttp/psr7/docs/stream-helpers.md

# Stream Helpers

This page covers `GuzzleHttp\Psr7\Utils` helper methods for creating, copying,
hashing, reading, and safely opening PSR-7 streams. For stream implementations
and decorators, see [Streams and Decorators](streams-and-decorators.md).

## `GuzzleHttp\Psr7\Utils::copyToStream`

`public static function copyToStream(StreamInterface $source, StreamInterface $dest, int $maxLen = -1): int`

Copy the contents of a stream into another stream until the given number of
bytes have been read, returning the number of bytes copied as an `int`. On
32-bit PHP, an unbounded copy larger than `PHP_INT_MAX` bytes cannot be
represented by that return type. 64-bit PHP is not affected.

The destination must accept writes that make positive progress. Streams that
return 0 as a backpressure or drop signal (a `BufferStream` at its high water
mark, or a full `DroppingStream`) will cause this method to throw. For full
copies, use a normal writable stream such as a file or `php://temp` stream.

Throws `GuzzleHttp\Psr7\Exception\TimeoutException` when PHP-style timeout
metadata can be detected after a source read or destination write cannot make
progress.

## `GuzzleHttp\Psr7\Utils::copyToString`

`public static function copyToString(StreamInterface $stream, int $maxLen = -1): string`

Copy the contents of a stream into a string until the given number of bytes have
been read.

Throws `GuzzleHttp\Psr7\Exception\TimeoutException` when PHP-style timeout
metadata can be detected after a stream read cannot make progress.

## `GuzzleHttp\Psr7\Utils::hash`

`public static function hash(StreamInterface $stream, string $algo, bool $rawOutput = false): string`

Calculate a hash of a stream.

This method reads the entire stream to calculate a rolling hash, based on PHP's
`hash_init` functions.

Throws `GuzzleHttp\Psr7\Exception\TimeoutException` when PHP-style timeout
metadata can be detected after a stream read cannot make progress.

## `GuzzleHttp\Psr7\Utils::readLine`

`public static function readLine(StreamInterface $stream, ?int $maxLength = null): string`

Read a line from the stream up to the maximum allowed buffer length.

Throws `GuzzleHttp\Psr7\Exception\TimeoutException` when PHP-style timeout
metadata can be detected after a stream read cannot make progress.

## `GuzzleHttp\Psr7\Utils::streamFor`

`public static function streamFor(resource|string|null|StreamInterface|callable|\Iterator|\Stringable $resource = '', array $options = []): StreamInterface`

Create a new stream based on the input type.

Options are provided as an associative array that can contain the following
keys:

- metadata: Array of custom metadata.
- size: Size of the stream.

This method accepts the following `$resource` types:

- `Psr\Http\Message\StreamInterface`: Returns the value as-is.
- `string`: Creates a stream object that uses the given string as the contents.
- `resource`: Creates a stream object that wraps the given PHP stream resource.
- `Iterator`: If the provided value implements `Iterator`, then a read-only
  stream object will be created that wraps the given iterable. Each time the
  stream is read from, data from the iterator will fill a buffer and will be
  continuously called until the buffer is equal to the requested read size.
  Yielded strings, integers, finite floats, booleans, `null`, and stringable
  objects are converted to string chunks; non-finite floats and other values
  throw `UnexpectedValueException` when the stream is read. Values that
  stringify to an empty string are skipped while the iterator advances.
  Subsequent read calls will first read from the buffer and then call `next` on
  the underlying iterator until it is exhausted.
- `object` with `__toString()`: If the object has the `__toString()` method, the
  object will be cast to a string and then a stream will be returned that uses
  the string value.
- `NULL`: When `null` is passed, an empty stream object is returned.
- `callable`: When a callable array, closure, or invokable object is passed and
  no earlier resource or object rule applies, a read-only stream object will be
  created that invokes the given callable. The callable is invoked with the
  suggested number of bytes to read. The callable can return fewer or more bytes
  than requested, but MUST return a non-empty string to provide data and MUST
  return `false` or `null` when there is no more data to return. Any additional
  bytes will be buffered and used in subsequent reads. String inputs are always
  treated as string bodies, even when they name callable functions.

```php
$stream = GuzzleHttp\Psr7\Utils::streamFor('foo');
$stream = GuzzleHttp\Psr7\Utils::streamFor(fopen('/path/to/file', 'r'));

$generator = function ($bytes) {
    for ($i = 0; $i < $bytes; $i++) {
        yield ' ';
    }
};

$stream = GuzzleHttp\Psr7\Utils::streamFor($generator(100));
```

## `GuzzleHttp\Psr7\Utils::tryFopen`

`public static function tryFopen(string $filename, string $mode): resource`

Safely opens a PHP stream resource using a filename.

When `fopen()` fails, PHP normally raises a warning. This function adds an error
handler that checks for errors and throws an exception instead.

## `GuzzleHttp\Psr7\Utils::tryGetContents`

`public static function tryGetContents(resource $stream): string`

Safely gets the contents of a given stream.

When `stream_get_contents()` fails, PHP normally raises a warning. This function
adds an error handler that checks for errors and throws an exception instead.

Throws `GuzzleHttp\Psr7\Exception\TimeoutException` when PHP-style timeout
metadata can be detected after the stream read cannot make progress.

## Related

- [Streams and Decorators](streams-and-decorators.md)
- [PSR-17 Factories](psr-17-factories.md)
- [Message Helpers](message-helpers.md)