Add docs for registerGlobalStreamWrapperAlias

Author: GromNaN

docs/reference/class/MongoDBGridFSBucket.txt

@@ -55,5 +55,6 @@ Methods
    /reference/method/MongoDBGridFSBucket-openDownloadStream
    /reference/method/MongoDBGridFSBucket-openDownloadStreamByName
    /reference/method/MongoDBGridFSBucket-openUploadStream
+   /reference/method/MongoDBGridFSBucket-registerGlobalStreamWrapperAlias
    /reference/method/MongoDBGridFSBucket-rename
    /reference/method/MongoDBGridFSBucket-uploadFromStream

docs/reference/method/MongoDBGridFSBucket-registerGlobalStreamWrapperAlias.txt

@@ -0,0 +1,80 @@
+============================================
+MongoDB\\GridFS\\Bucket::registerGlobalStreamWrapperAlias()
+============================================
+
+.. versionadded:: 1.18
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Definition
+----------
+
+.. phpmethod:: MongoDB\\GridFS\\Bucket::registerGlobalStreamWrapperAlias()
+
+   Register an alias to enable basic filename access for a GridFS bucket
+
+   .. code-block:: php
+
+      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
+--------
+
+Files can then be accessed using the following pattern: ``gridfs://<bucket-alias>/<filename>``
+
+Supported stream functions:
+
+- ``file_exists()``
+- ``file_get_contents()``
+- ``file_put_contents()``
+- ``fopen()`` (with "r", "rb", "w", and "wb" modes)
+- ``filesize()``
+- ``filemtime()``
+
+Example
+-------
+
+.. code-block:: php
+
+   <?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');
+
+The output would then resemble:
+
+.. code-block:: none
+
+   bool(false)
+   bool(true)
+   Hello, GridFS!
+
+

examples/gridfs-stream-wrapper.php

@@ -0,0 +1,60 @@
+<?php
+
+/**
+ * For applications that need to interact with GridFS using only a filename string,
+ * a bucket can be registered with an alias. Files can then be accessed using the
+ * following pattern:
+ *     gridfs://<bucket-alias>/<filename>
+ */
+
+declare(strict_types=1);
+
+namespace MongoDB\Examples;
+
+use MongoDB\Client;
+
+use function file_exists;
+use function file_get_contents;
+use function file_put_contents;
+use function getenv;
+use function stream_context_create;
+
+use const PHP_EOL;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$client = new Client(getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/');
+$bucket = $client->test->selectGridFSBucket();
+$bucket->drop();
+
+// Register the alias "mybucket" for default bucket of the "test" database
+$bucket->registerGlobalStreamWrapperAlias('mybucket');
+
+echo 'File exists: ';
+echo file_exists('gridfs://mybucket/hello.txt') ? 'yes' : 'no';
+echo PHP_EOL;
+
+echo 'Writing file';
+file_put_contents('gridfs://mybucket/hello.txt', 'Hello, GridFS!');
+echo PHP_EOL;
+
+echo 'File exists: ';
+echo file_exists('gridfs://mybucket/hello.txt') ? 'yes' : 'no';
+echo PHP_EOL;
+
+echo 'Reading file: ';
+echo file_get_contents('gridfs://mybucket/hello.txt');
+echo PHP_EOL;
+
+echo 'Writing new version of the file';
+file_put_contents('gridfs://mybucket/hello.txt', 'Hello, GridFS! (v2)');
+echo PHP_EOL;
+
+echo 'Reading new version of the file: ';
+echo file_get_contents('gridfs://mybucket/hello.txt');
+echo PHP_EOL;
+
+echo 'Reading previous version of the file: ';
+$context = stream_context_create(['gridfs' => ['revision' => -2]]);
+echo file_get_contents('gridfs://mybucket/hello.txt', false, $context);
+echo PHP_EOL;

src/GridFS/Bucket.php

@@ -591,11 +591,15 @@ public function openUploadStream(string $filename, array $options = [])
     }
 
     /**
-     * For legacy applications that needs to open stream from a string, the bucket can be registered in the stream
-     * wrapper to be used by default when no GridFS context is provided.
-     * Supported file name must follow this pattern:
+     * Register an alias to enable basic filename access for this bucket
+     *
+     * For applications that need to interact with GridFS using only a filename
+     * string, a bucket can be registered with an alias. Files can then be
+     * accessed using the following pattern:
      *     gridfs://<bucket-alias>/<filename>
      *
+     * Read operations will always target the most recent revision of a file.
+     *
      * @param non-empty-string string $alias The alias to use for the bucket
      */
     public function registerGlobalStreamWrapperAlias(string $alias): void

tests/ExamplesTest.php

@@ -127,6 +127,21 @@ public static function provideExamples(): Generator
 )
 OUTPUT;
 
+        $expectedOutput = <<<'OUTPUT'
+File exists: no
+Writing file
+File exists: yes
+Reading file: Hello, GridFS!
+Writing new version of the file
+Reading new version of the file: Hello, GridFS! (v2)
+Reading previous version of the file: Hello, GridFS!
+OUTPUT;
+
+        yield 'gridfs-stream-wrapper' => [
+            'file' => __DIR__ . '/../examples/gridfs-stream-wrapper.php',
+            'expectedOutput' => $expectedOutput,
+        ];
+
         yield 'persistable' => [
             'file' => __DIR__ . '/../examples/persistable.php',
             'expectedOutput' => $expectedOutput,