Docs Menu
Docs Home
/ / /
PHP Library Manual
/ /

MongoDB\GridFS\Bucket::registerGlobalStreamWrapperAlias()

On this page

  • Definition
  • Parameters
  • Behavior
  • Example

New in version 1.18.

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
$alias : array
A non-empty string used to identify the GridFS bucket when accessing files using the gridfs:// stream wrapper.

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.

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!

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

The output would then resemble:

Hello, GridFS! (v0)

Back

openUploadStream()