Open and Close

How to open

File

Use the open() method to open a stream to a file or URL.

use Aedart\Streams\FileStream;

$stream = FileStream::open('recipients.txt', 'r+b');

Behind the scene, PHP's fopen() is used.

Memory

To open a stream to php://memory, use the openMemory() method.

$stream = FileStream::openMemory();

See PHP Documentation for additional details.

Temporary

You may also open a stream to php://temp, by using openTemporary()

$stream = FileStream::openTemporary();

To specify the maximum memory limit, before PHP's internal mechanisms write to a physical file, use the 2nd argument.

$stream = FileStream::openTemporary('r+b', 5 * 1024 * 1024);

See PHP Documentation for additional details.

Existing resource

If you already have an existing resource to a file or URL, you can "wrap" it into a stream component, by using the make() method.

$resource = fopen('team.txt', 'w+b');

// ...Later in your application...
$stream = Stream::make($resource);

Existing PSR-Stream

Use the makeFrom() method when you need to wrap an existing StreamInterface component.

$stream = Stream::makeFrom($psrStream);

SplFileInfo

Available since v7.4.x

When working with uploaded files, e.g. from Laravel or Symfony (SplFileInfo instances), then you can open a file stream using the openFileInfo() method.

$stream = FileStream::openFileInfo($uploadedFile, 'r');

PSR Uploaded File

Available since v7.4.x

You may also create a file stream instance for an existing PSR-7 Uploaded File instance, using the openUploadedFile() method.

$stream = FileStream::openUploadedFile($psrUploadedFile);

// Copies the PSR stream into the file stream...
$stream = FileStream::openUploadedFile(
    file: $psrUploadedFile,
    asCopy: true
);

Lazy

Lastly, you may also open a stream after you have created a Stream or FileStream, using a callback. The openUsing() accepts a callback, which must return a valid resource of the type "stream".

use Aedart\Streams\FileStream;

$stream = new FileStream();

// ...later in your application...
$stream->openUsing(function() {
    return fopen('countries.txt', 'rb');
});

if (!$stream->isOpen()) {
    $stream->openUsing(function() {
        return fopen('countries.txt', 'rb');
    });
} else {
    // ...do something else...
}

Cloning

$stream = FileStream::open('locations.txt', 'r');
$clone = clone $stream; // Fails - StreamException is thrown!

How to close

Close stream

When you need to close a stream, invoke the close() method. The underlying resource will be detached and closed using PHP's fclose().

$stream->close();

Detaching resource

If you do not wish to close the stream, but you want to detach - to separate the underlying resource, from the stream instance, then you can use the detach() method.

$resource = $stream->detach();

// ...stream instance is now useless!

$resource = $stream->detach();

// ...later... attempt to re-open using same resource
// and same stream instance - NOT RECOMMENDED!
$stream->openUsing(fn () => $resource);