Improve docs

Author: GromNaN

docs/reference/method/MongoDBGridFSBucket-registerGlobalStreamWrapperAlias.txt

@@ -1,6 +1,6 @@
-============================================
+===========================================================
 MongoDB\\GridFS\\Bucket::registerGlobalStreamWrapperAlias()
-============================================
+===========================================================
 
 .. versionadded:: 1.18
 
@@ -17,14 +17,13 @@ Definition
 
 .. phpmethod:: MongoDB\\GridFS\\Bucket::registerGlobalStreamWrapperAlias()
 
-   Register an alias to enable basic filename access for a GridFS bucket
+   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
-
+      function registerGlobalStreamWrapperAlias(string $alias): void
 
 Parameters
 ----------
@@ -33,25 +32,43 @@ Parameters
   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>``
+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)
 
+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 options ``gridfs['chunkSizeBytes']``
+and ``gridfs['disableMD5']`` options. If omitted, the defaults are inherited from the
+``Bucket`` instance options.
+
 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
@@ -77,4 +94,40 @@ The output would then resemble:
    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)

tests/GridFS/FunctionalTestCase.php

@@ -4,7 +4,6 @@
 
 use MongoDB\Collection;
 use MongoDB\GridFS\Bucket;
-use MongoDB\GridFS\StreamWrapper;
 use MongoDB\Tests\FunctionalTestCase as BaseFunctionalTestCase;
 
 use function fopen;
@@ -35,13 +34,6 @@ public function setUp(): void
         $this->filesCollection = $this->createCollection($this->getDatabaseName(), 'fs.files');
     }
 
-    public function tearDown(): void
-    {
-        StreamWrapper::setContextResolver('default', null);
-
-        parent::tearDown();
-    }
-
     /**
      * Asserts that a variable is a stream containing the expected data.
      *

tests/GridFS/StreamWrapperFunctionalTest.php

@@ -6,7 +6,9 @@
 use MongoDB\BSON\UTCDateTime;
 use MongoDB\GridFS\Exception\FileNotFoundException;
 use MongoDB\GridFS\Exception\LogicException;
+use MongoDB\GridFS\StreamWrapper;
 
+use function copy;
 use function fclose;
 use function feof;
 use function file_exists;
@@ -51,6 +53,13 @@ public function setUp(): void
         ]);
     }
 
+    public function tearDown(): void
+    {
+        StreamWrapper::setContextResolver('bucket', null);
+
+        parent::tearDown();
+    }
+
     public function testReadableStreamClose(): void
     {
         $stream = $this->bucket->openDownloadStream('length-10');
@@ -313,9 +322,9 @@ public function testFileNoFoundWithContextResolver(): void
     public function testFileNoFoundWithoutDefaultResolver(): void
     {
         $this->expectException(LogicException::class);
-        $this->expectExceptionMessage('GridFS stream wrapper has no bucket alias: "not-registered-alias"');
+        $this->expectExceptionMessage('GridFS stream wrapper has no bucket alias: "bucket"');
 
-        fopen('gridfs://not-registered-alias/filename', 'w');
+        fopen('gridfs://bucket/filename', 'w');
     }
 
     public function testFileStats(): void
@@ -324,6 +333,7 @@ public function testFileStats(): void
         $path = 'gridfs://bucket/filename';
 
         $this->assertFalse(file_exists($path));
+        $this->assertFalse(is_file($path));
 
         $time = time();
         $this->assertSame(6, file_put_contents($path, 'foobar'));
@@ -336,5 +346,8 @@ public function testFileStats(): void
         $this->assertSame(6, filesize($path));
         $this->assertGreaterThanOrEqual($time, filemtime($path));
         $this->assertLessThanOrEqual(time(), filemtime($path));
+
+        copy($path, $path . '.copy');
+        $this->assertTrue(file_exists($path . '.copy'));
     }
 }