PSR 7: Stream Example

PSR-7 HTTP Message Interfaces

Namespace

Shieldon\Psr7\Stream

Stream

• __construct
• isWritable
• isReadable
• isSeekable
• close
• detach
• getSize
• tell
• eof
• seek
• rewind
• write
• read
• getContents
• getMetadata
• __toString

__construct

• param resource stream * A valid resource.

Example:

$stream = new \Shieldon\Psr7\Stream(fopen('php://temp', 'r+'));

isWritable()

Write data to the stream.

• return bool

Example:

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new \Shieldon\Psr7\Stream($resource);

if ($stream->isWritable()) {
    echo 'File is writable';
}
// Outputs: File is writable

isReadable()

Returns whether or not the stream is readable.

• return bool

Example:

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new \Shieldon\Psr7\Stream($resource);

if ($stream->isReadable()) {
    echo 'File is readable';
}
// Outputs: File is readable

isSeekable()

Seek to a position in the stream.

• return bool

Example:

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new \Shieldon\Psr7\Stream($resource);

if ($stream->isSeekable()) {
    echo 'File is seekable';
}
// Outputs: File is seekable

close()

loses the stream and any underlying resources.

• return void

Example:

$stream = new Stream(fopen('php://temp', 'r+'));
/* ... do something ... */
$stream->close();

detach()

Separates any underlying resources from the stream. After the stream has been detached, the stream is in an unusable state.

• return resource|null

Example:

$stream = new Stream(fopen('php://temp', 'r+'));
/* ... do something ... */
$legacy = $stream->detach();

if (is_resouce($legacy)) {
    echo 'Resource is detached.';
}
// Outputs: Resource is detached.

$legacy = $stream->detach();

if (is_null($legacy)) {
    echo 'Resource has been null.';
}
// Outputs: Resource has been null.

getSize()

Get the size of the stream if known.

• return int|null

Example:

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new \Shieldon\Psr7\Stream($resource);

echo $stream->getSize();
// Outputs: 15166

tell()

Returns the current position of the file read/write pointer

• return int Position of the file pointer

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new Stream($resource);

$stream->seek(10);
echo $stream->tell();
// Outputs: 10

$stream->rewind();
echo $stream->tell();
// Outputs: 0

$stream->close();

eof()

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

• return bool

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new Stream($resource);

$stream->seek(10);

if ($stream->eof()) {
    echo 'The position of the file pointer of the stream is at the end.';
} else {
    echo 'Not at the end.';
}
// Outputs: Not at the end.

$stream->seek(15166);

if ($stream->eof()) {
    echo 'The position of the file pointer of the stream is at the end.';
} else {
    echo 'Not at the end.';
}
// Outputs: The position of the file pointer of the stream is at the end.

seek($offset, $whence)

Seek to a position in the stream.

• param int offset * Stream offset.
• param int whence = SEEK_SET Specifies how the cursor position will be calculated based on the seek offset.
• return void

Example:

// See eof() example.

rewind()

Seek to the beginning of the stream.

• return void

Example:

// See tell() example.

write($string)

• param string string * The string that is to be written.
• return int Returns the number of bytes written to the stream.

Example:

$stream = new Stream(fopen('php://temp', 'r+'));
$stream->write('Foo Bar');

echo $stream->getContents();

// Outputs: Foo Bar

read($length)

Read data from the stream.

• param int length * Read up to $length bytes from the object and return them.
• return string

Example:

$stream = new Stream(fopen('php://temp', 'r+'));
$stream->write('Glory to Hong Kong');

echo $stream->read(5);

// Outputs: Glory

getContents()

Returns the remaining contents in a string

• return string

Example:

$stream = new Stream(fopen('php://temp', 'r+'));
$stream->write('Glory to Hong Kong');

echo $stream->getContents();

// Outputs: Glory to Hong Kong

getMetadata($key)

Get stream metadata as an associative array or retrieve a specific key.

• param string key = null Specific metadata to retrieve.
• return array|mixed|null

Example:

$resource = fopen(BOOTSTRAP_DIR . '/sample/shieldon_logo.png', 'r+');
$stream = new Stream($resource);
$meta = $stream->getMetadata();

print(print_r($queryParams, true));

/* Outputs:

    Array
    (
        [timed_out] => false
        [blocked] => true
        [eof] => false
        [wrapper_type] => plainfile
        [stream_type] => STDIO
        [mode] => r+
        [unread_bytes] => 0
        [seekable] => true
        [uri] => /home/terrylin/data/psr7/tests/sample/shieldon_logo.png
    )
*/

echo $stream->getMetadata('mode')
// Outputs: r+

__toString()

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

• return string

Example:

$stream = new Stream(fopen('php://temp', 'r+'));
$stream->write('Foo Bar');

echo $stream;
// Outputs: Foo Bar