Open and Close

• How to open
  • File
  • Memory
  • Temporary
  • Existing resource
  • Existing PSR-Stream
  • SplFileInfo
  • PSR Uploaded File
  • 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.

SplFileInfo

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

Filename

For Laravel and Symfony, the uploaded file's getClientOriginalName() return value is used as the stream's filename() value.

PSR Uploaded File

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

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

WARNING

Unless specified otherwise, the openUploadedFile() method will automatically detach the uploaded file's underlying stream. If you wish to avoid this, then set the $asCopy argument to true (defaults to false).

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

For more information, see the source code of openUploadedFile() and see also copy from documentation.

Filename

The uploaded file's getClientFilename() return value is used as the stream's filename() value.

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.