PHPLIB-1206 Add bucket alises for context resolver using GridFS StreamWrapper (#1138)

Author: GromNaN

source/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

source/reference/method/MongoDBGridFSBucket-registerGlobalStreamWrapperAlias.txt

@@ -0,0 +1,132 @@
+===========================================================
+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()
+
+   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>`).
+
+   .. 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
+--------
+
+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:
+
+- :php:`copy() <copy>`
+- :php:`file_exists() <file_exists>`
+- :php:`file_get_contents() <file_get_contents>`
+- :php:`file_put_contents() <file_put_contents>`
+- :php:`filemtime() <filemtime>`
+- :php:`filesize() <filesize>`
+- :php:`file() <file>`
+- :php:`fopen() <fopen>` (with "r", "rb", "w", and "wb" modes)
+
+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.
+
+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.
+
+.. 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!
+
+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.
+
+.. code-block:: php
+
+   <?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:
+
+.. code-block:: none
+
+   Hello, GridFS! (v0)