PHP Luminova: HTTP Message and File Stream

The Luminova Data Stream class provides a simple wrapper for working with file stream resources. It implements Stringable, so the stream can be converted to a string when needed.

The stream class fully adhara to PSR-7 Psr\Http\Message\StreamInterface guidelines, making it fully compatible with Luminova’s HTTP Novio Client.

Class Definition

• Class namespace: Luminova\Http\Message\Stream
• This class implements: Psr\Http\Message\StreamInterface, Stringable

Examples

Basic Usage

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

use Luminova\Http\Message\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

namespace App\Utils;

use Luminova\Http\Message\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

Create a new stream instance using an underlying PHP resource.

public __construct(resource $resource): mixed

Parameters:

Throws:

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

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.

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.

buffer

Read the full stream content from the beginning.

This method rewinds the stream pointer (if seekable) and then reads the entire body in one operation. It ignores the current pointer position and always returns the complete data stored in the stream.

public buffer(): string

Return Value:

string - Returns the full content of the stream.

Throws:

• \Luminova\Exceptions\RuntimeException - If the stream cannot be read.

Useful when you want the whole response body regardless of whether it has been partially read earlier.

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.

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.

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.

toString

Reads the entire stream and returns it contents as string.

public toString(): string

Return Value:

string - Return the contents of the stream.

isSeekable

Checks if the stream is seekable.

public isSeekable(): bool

Return Value:

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

isWritable

Checks if the stream is writable.

public isWritable(): bool

Return Value:

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

isReadable

Checks if the stream is readable.

public isReadable(): bool

Return Value:

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

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.

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.

getMetadata

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

public getMetadata(?string $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.