# Trait HttpSoft\Message\StreamTrait

Trait implementing the methods defined in Psr\Http\Message\StreamInterface, used within HttpSoft\Message\Stream.

# Public methods

See the original detailed description of the methods in the Psr\Http\Message\StreamInterface.

# __destruct

Closes the stream and any underlying resources when the instance is destructed.

public function __destruct();

# __toString

Reads all data from the stream into a string, from the beginning to end.

public function __toString(): string;

If stream is not readable, the \RuntimeException exception will be thrown.

# close

Closes the stream and any underlying resources.

public function close(): void;

# detach

Separates any underlying resources from the stream.

/**
 * @return resource|null
 */
public function detach();

After the stream has been detached, the stream is in an unusable state.

# getSize

Returns the size in bytes if known, or null if unknown.

public function getSize(): ?int;

# tell

Returns the current position of the file read/write pointer.

public function tell(): int;

If cannot tell the pointer position, the \RuntimeException exception will be thrown.

# eof

Returns true if the pointer is at the end of the stream.

public function eof(): bool;

# isSeekable

Returns true if the stream, is allowed to seek the pointer position.

public function isSeekable(): bool;

# seek

Seek to a pointer position in the stream.

/**
 * @param int $offset
 * @param int $whence
 */
public function seek($offset, $whence = SEEK_SET): void;

If cannot seek the pointer position, the \RuntimeException exception will be thrown.

# rewind

Seek to the beginning of the stream.

public function rewind(): void;

If cannot seek to the beginning of the stream, the \RuntimeException exception will be thrown.

# isWritable

Returns true if the stream is writable.

public function isWritable(): bool;

# write

Write data to the stream and returns the number of bytes written to the stream.

/**
 * @param string $string
 * @return int
 */
public function write($string): int;

If cannot write data to the stream, the \RuntimeException exception will be thrown.

$stream = new Stream('php://temp', 'wb+');
(string) $stream; // ''
$stream->write('content');
(string) $stream; // 'content'

$stream = new Stream('php://temp', 'r');
$stream->write('content'); // throws RuntimeException

# isReadable

Returns true if the stream is readable.

public function isReadable(): bool;

# read

Reads and returns data from the stream by the number of bytes passed, or an empty string if there are no bytes available.

/**
 * @param int $length
 * @return string
 */
public function read($length): string;

If cannot read data from the stream, the \RuntimeException exception will be thrown.

$stream = new Stream('path/to/file', 'r');
$stream->read(5); // 'File '
$stream->getContents(); // 'content'
(string) $stream; // 'File content'

$stream = new Stream('path/to/file', 'w');
$stream->read(5); // throws RuntimeException

# getContents

Returns the remaining contents in a string.

public function getContents(): string;

If unable to read from the stream, or an error occurs while reading, the \RuntimeException exception will be thrown.

$stream = new Stream('path/to/file', 'r');
$stream->read(5); // 'File '
$stream->getContents(); // 'content'
(string) $stream; // 'File content'

$stream = new Stream('path/to/file', 'r');
$stream->getContents(); // 'File content'
$stream->getContents(); // ''
(string) $stream; // 'File content'

$stream = new StreamPhpInput('path/to/file');
$stream->getContents(); // 'File content'
$stream->getContents(); // 'File content'
(string) $stream; // 'File content'

$stream = new Stream('path/to/file', 'w');
$stream->getContents(); // throws RuntimeException

# getMetadata

Returns stream metadata as an associative array, or retrieves a value by a specific key.

/**
 * @param string $key
 * @return array|mixed|null 
 */
public function getMetadata($key = null);

Returns an associative array if no key is provided. Returns a specific key value if a key is provided and the value is found, or null if the key is not found.

$stream = new Stream('php://temp', 'wb+');

$stream->getMetadata();
/*
[
    'wrapper_type' => 'PHP',
    'stream_type' => 'TEMP',
    'mode' => 'w+b',
    'unread_bytes' => 0,
    'seekable' => true,
    'uri' => 'php://temp',
];
*/

$stream->getMetadata('wrapper_type'); // 'PHP'
$stream->getMetadata('stream_type'); // 'TEMP'
$stream->getMetadata('mode'); // 'w+b'
$stream->getMetadata('unread_bytes'); // 0
$stream->getMetadata('seekable'); // true
$stream->getMetadata('uri'); // 'php://temp'

$stream->getMetadata('no-key'); // null