RangeStream

API reference › PSR bridge › adapter › RangeStream

final class	yii2\extensions\psrbridge\adapter\RangeStream
Implements	Psr\Http\Message\StreamInterface
Source	src/adapter/RangeStream.php

Read-only PSR-7 stream limited to a byte range of an underlying stream.

Wraps any StreamInterface and exposes only bytes in the inclusive range [$begin, $end], enforcing the upper bound so consumers cannot read past $end even when calling StreamInterface::getContents() or repeated StreamInterface::read() calls. Reads proxy to the underlying stream chunk by chunk without buffering the range into memory or temporary storage.

This is a bounded view, not a transparent decorator for the wrapped stream. The wrapped stream resource and its original URI can represent bytes outside the declared range, so they are not exposed through detach() or getMetadata('uri').

Methods

Method	Description	Defined by
__construct()	Creates a new instance of the RangeStream class.	RangeStream
__toString()	Returns range contents as a string, rewinding seekable streams and returning an empty string on failure.	RangeStream
close()	Closes the underlying stream and releases the internal reference.	RangeStream
detach()	Closes the wrapped stream and releases the internal reference without exposing the underlying resource.	RangeStream
eof()	Indicates whether the read cursor has reached the end of the range or the underlying stream.	RangeStream
getContents()	Reads every remaining byte within the range and returns them as a single string.	RangeStream
getMetadata()	Returns metadata associated with this bounded stream view.	RangeStream
getSize()	Returns the size of the range, not the size of the underlying stream.	RangeStream
isReadable()	Indicates whether the underlying stream reports as readable.	RangeStream
isSeekable()	Indicates whether seeking within the range is supported.	RangeStream
isWritable()	Indicates that the stream is read-only.	RangeStream
read()	Reads up to $length bytes from the current position, capped at the bytes remaining in the range.	RangeStream
rewind()	Rewinds the read cursor to the start of the range.	RangeStream
seek()	Seeks to an offset relative to the range, clamped to [0, $length].	RangeStream
tell()	Returns the current read position relative to the start of the range.	RangeStream
write()	Rejects every write attempt because the stream is read-only.	RangeStream

Method details

__construct()

public function __construct(Psr\Http\Message\StreamInterface $stream, int $begin, int $end)

Creates a new instance of the RangeStream class.

Rewinds the underlying stream to $begin only when it reports as seekable; non-seekable streams must already be positioned at $begin by the caller.

Parameters

Parameter	Type	Description
$stream	Psr\Http\Message\StreamInterface	Underlying stream to expose a bounded view of.
$begin	int	Inclusive byte offset where the range starts (0-based, absolute in the underlying stream).
$end	int	Inclusive byte offset where the range ends (absolute in the underlying stream).

Throws

• RuntimeException: when the range is invalid or initial positioning fails.

__toString()

public function __toString(): string

Returns range contents as a string, rewinding seekable streams and returning an empty string on failure.

On non-seekable streams, only the remaining range bytes can be returned.

Returns

string: Bytes within the range, or empty string when any error occurs.

close()

public function close(): void

Closes the underlying stream and releases the internal reference.

detach()

public function detach(): resource|null

Closes the wrapped stream and releases the internal reference without exposing the underlying resource.

The wrapped resource is not detached because it can contain bytes outside this bounded view. Returning that resource would allow consumers to bypass the range limit. Consumers that need the body contents must read through read() or getContents().

Returns

resource|null: Always null; no detachable resource can safely represent the bounded view.

eof()

public function eof(): bool

Indicates whether the read cursor has reached the end of the range or the underlying stream.

Returns

bool: true when no more bytes can be read within the range; false otherwise.

getContents()

public function getContents(): string

Reads every remaining byte within the range and returns them as a single string.

Iterates read() in chunks of READ_BUFFER_LENGTH bytes until the range or the underlying stream reaches EOF; no intermediate copy of the full range is held by the underlying stream.

Returns

string: Concatenation of every chunk read until the end of the range or underlying stream EOF.

getMetadata()

public function getMetadata(string|null $key = null): mixed

Returns metadata associated with this bounded stream view.

Resource locator metadata such as uri is omitted because the underlying URI identifies the unbounded wrapped stream, not this range-limited view.

Parameters

Parameter	Type	Description
$key	string|null	Specific metadata key, or null to return the full metadata array.

Returns

mixed: Metadata value for $key, the full metadata array when $key is null, or null when no stream is available and $key is provided.

getSize()

public function getSize(): int|null

Returns the size of the range, not the size of the underlying stream.

Returns

int|null: Length of the range in bytes, or null after the underlying stream has been detached or closed.

isReadable()

public function isReadable(): bool

Indicates whether the underlying stream reports as readable.

Returns

bool: true when the underlying stream is readable; false otherwise or when no stream is available.

isSeekable()

public function isSeekable(): bool

Indicates whether seeking within the range is supported.

Returns

bool: true when the underlying stream is seekable; false otherwise or when no stream is available.

isWritable()

public function isWritable(): bool

Indicates that the stream is read-only.

Returns

bool: Always false; range streams reject all writes.

read()

public function read(int $length): string

Reads up to $length bytes from the current position, capped at the bytes remaining in the range.

Parameters

Parameter	Type	Description
$length	int	Maximum number of bytes to read.

Returns

string: Bytes read, or empty string at EOF, when closed or detached, or when $length is 0.

Throws

• RuntimeException: when the length is negative or an underlying operation fails.

rewind()

public function rewind(): void

Rewinds the read cursor to the start of the range.

Throws

• RuntimeException: when the stream is closed or seeking fails.

seek()

public function seek(int $offset, int $whence = \SEEK_SET): void

Seeks to an offset relative to the range, clamped to [0, $length].

Parameters

Parameter	Type	Description
$offset	int	Byte offset to seek to, interpreted according to $whence.
$whence	int	One of SEEK_SET (absolute), SEEK_CUR (relative to current), SEEK_END (relative to end).

Throws

• RuntimeException: when the target/mode is invalid, the stream is closed, or seeking fails.

tell()

public function tell(): int

Returns the current read position relative to the start of the range.

Returns

int: Position in bytes within [0, $length].

Throws

• RuntimeException: when the stream is closed or its position is unavailable.

write()

public function write(string $string): int

Rejects every write attempt because the stream is read-only.

Parameters

Parameter	Type	Description
$string	string	Bytes the caller attempted to write (ignored).

Returns

int: Never returns; included to satisfy the StreamInterface contract.

Throws

• RuntimeException: always.