MongoDB\GridFS\Bucket::registerGlobalStreamWrapperAlias()

On this page

Definition

Parameters
Behavior
Example

New in version 1.18.

Definition

MongoDB\GridFS\Bucket::registerGlobalStreamWrapperAlias()

Registers an alias for the bucket, which enables files within the bucket to be accessed using a basic filename string (e.g. gridfs://<bucket-alias>/<filename>).

function registerGlobalStreamWrapperAlias(string $alias): void

Parameters

$alias : array: A non-empty string used to identify the GridFS bucket when accessing files using the gridfs:// stream wrapper.

Behavior

After registering an alias for the bucket, the most recent revision of a file can be accessed using a filename string in the form gridfs://<bucket-alias>/<filename>.

Supported stream functions:

copy()
file_exists()
file_get_contents()
file_put_contents()
filemtime()
filesize()
file()
fopen() with "r", "rb", "w", and "wb" modes
rename()
unlink()

In read mode, the stream context can contain the option gridfs['revision'] to specify the revision number of the file to read. If omitted, the most recent revision is read (revision -1).

In write mode, the stream context can contain the option gridfs['chunkSizeBytes']. If omitted, the defaults are inherited from the Bucket instance option.

The functions rename and unlink will rename or remove all revisions of a filename. If the filename does not exist, these functions throw a FileNotFoundException.

Example

Read and write to a GridFS bucket using the `gridfs://` stream wrapper

The following example demonstrates how to register an alias for a GridFS bucket and use the functions file_exists(), file_get_contents(), and file_put_contents() to read and write to the bucket.

Each call to these functions makes a request to the server.

<?php
$database = (new MongoDB\Client)->selectDatabase('test');
$bucket = $database->selectGridFSBucket();
$bucket->registerGlobalStreamWrapperAlias('mybucket');
var_dump(file_exists('gridfs://mybucket/hello.txt'));
file_put_contents('gridfs://mybucket/hello.txt', 'Hello, GridFS!');
var_dump(file_exists('gridfs://mybucket/hello.txt'));
echo file_get_contents('gridfs://mybucket/hello.txt');
unlink('gridfs://mybucket/hello.txt');

The output would then resemble:

bool(false)
bool(true)
Hello, GridFS!

Read a specific revision of a file

Using a stream context, you can specify the revision number of the file to read. If omitted, the most recent revision is read.

<?php
$database = (new MongoDB\Client)->selectDatabase('test');
$bucket = $database->selectGridFSBucket();
$bucket->registerGlobalStreamWrapperAlias('mybucket');
// Creating revision 0
$handle = fopen('gridfs://mybucket/hello.txt', 'w');
fwrite($handle, 'Hello, GridFS! (v0)');
fclose($handle);
// Creating revision 1
$handle = fopen('gridfs://mybucket/hello.txt', 'w');
fwrite($handle, 'Hello, GridFS! (v1)');
fclose($handle);
// Read revision 0
$context = stream_context_create([
     'gridfs' => ['revision' => 0],
]);
$handle = fopen('gridfs://mybucket/hello.txt', 'r', false, $context);
echo fread($handle, 1024);