Open and Close

• How to open
  • File
  • Memory
  • Temporary
  • Existing resource
  • Existing PSR-Stream
  • Lazy
  • Cloning
• How to close
  • Close stream
  • Detaching resource

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);

WARNING

The makeFrom() will automatically detach the given StreamInterface component's underlying resource. This means that you will no longer be able to use the provided PSR stream instance.

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');
});

Info

openUsing() will fail if the stream instance already has a valid resource specified (when the stream is already open). Use the isOpen() method to determine if a stream can be opened.

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

Cloning

Not supported

Cloning an existing stream instance is not supported and will result in StreamException to be thrown.

$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!

Caution

When you detach the underlying resource from the stream, the stream instance becomes useless. You SHOULD avoid reusing or reopening a resource, when such is the case.

Not recommended

The following example is NOT recommended (even though it is possible)!

$resource = $stream->detach();

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

Future versions of Stream and FileStream may prohibit this behaviour.