PHP Luminova: PSR Stream Interface Implementation and Management

The Stream class provides a robust interface for working with stream resources in a consistent manner. It implements the \Stringable interface, allowing the object to be easily converted to a string. While the class supports all methods defined by the PSR StreamInterface, it is intentionally not implemented as a PSR interface. This design choice allows for seamless integration in cURL network client response without requiring the installation of PSR client libraries, making it ideal for simple network request implementations.

Class Definition

• Class namespace: \Luminova\Storages\Stream
• This class implements: \Stringable

Examples

Basic Usage

Here's how to create a stream and use its methods:

use Luminova\Storages\Stream;

// Create a stream from a string
$stream = new Stream(fopen('php://temp', 'r+'));
$stream->write("Hello, Luminova!");

// Read the contents of the stream
$stream->rewind();
echo $stream->toString(); // Output: Hello, Luminova!

Get the size of the stream:

echo $stream->getSize(); // Output: 19

Check if the stream is writable:

if ($stream->isWritable()) {
    $stream->write(" Adding more data.");
}

Read remaining contents

$stream->rewind();
echo $stream->getContents(); // Output: Hello, Luminova! Adding more data.

// Close the stream
$stream->close();

Advanced Usage

You can extend the Stream class and implement the PSR StreamInterface if needed. Here's an example:

// /app/Utils/MyStream.php

<?php
namespace App\Utils;

use Luminova\Storages\Stream;
use Psr\Http\Message\StreamInterface;

class MyStream extends Stream implements StreamInterface
{
    // Override the default method implementation
    public function close(): void
    {
        if(something){
            $this->doThat();
        }
        // Then call parent method if necessary
        parent::close();
    }

    // Additional methods can be implemented here as needed
}

Methods

constructor

Initialize the stream constructor with an underlying resource.

public __construct(private resource $resource): mixed

Parameters:

Throws:

• Luminova\Exceptions\InvalidArgumentException - if the provided resource is not a valid stream.

toString

Reads the entire stream and returns it contents as string.

public toString(): string

Return Value:

string - Return the contents of the stream.

close

Closes the stream and releases any resources associated with it.

public close(): void

detach

Detaches the underlying resource from the stream.

public detach(): ?resource

Return Value:

resource|null - Return the detached resource, or null if none is present.

getSize

Retrieves the size of the stream in bytes.

public getSize(): ?int

Return Value:

int|null - Return the size of the stream, or null if the size cannot be determined.

tell

Retrieves the current position of the stream pointer.

public tell(): int

Return Value:

int - Return the position of the stream pointer.

Throws:

• Luminova\Exceptions\RuntimeException - if the position cannot be determined.

eof

Determines if the stream has reached the end of file.

public eof(): bool

Return Value:

bool - Return true if the stream is at EOF, false otherwise.

isSeekable

Checks if the stream is seekable.

public isSeekable(): bool

Return Value:

bool - Return true if the stream is seekable, false otherwise.

seek

Seeks to a position within the stream.

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

Parameters:

Throws:

• Luminova\Exceptions\RuntimeException - if the stream is not seekable or if the seek operation fails.

rewind

Rewinds the stream to the beginning.

public rewind(): void

Throws:

• Luminova\Exceptions\RuntimeException - if the rewind operation fails.

isWritable

Checks if the stream is writable.

public isWritable(): bool

Return Value:

bool - Return true if the stream is writable, false otherwise.

write

Writes data to the stream.

public write(string $string): int

Parameters:

Return Value:

int - Return the number of bytes written to the stream.

Throws:

• Luminova\Exceptions\RuntimeException - if the stream is not writable or if the write operation fails.

isReadable

Checks if the stream is readable.

public isReadable(): bool

Return Value:

bool - Return true if the stream is readable, false otherwise.

read

Reads data from the stream.

public read(int $length): string

Parameters:

Return Value:

string - Return the data read from the stream.

Throws:

• Luminova\Exceptions\RuntimeException - if the stream is not readable or if the read operation fails.
• Luminova\Exceptions\InvalidArgumentException - if the length parameter is negative.

getContents

Retrieves the remaining contents of the stream as a string.

public getContents(): string

Return Value:

string - Return the remaining contents of the stream.

Throws:

• Luminova\Exceptions\RuntimeException - if the stream is not readable or if the content retrieval fails.

getMetadata

Retrieves metadata about the stream or a specific key from the metadata array.

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

Parameters:

Return Value:

mixed - Return the metadata value for the specified key, an array of all metadata if key is NULL, otherwise null or empty array.