PHPLIB-1248 Add examples on GridFS (#1196)

examples/gridfs_stream.php

@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * This example demonstrates how to use GridFS streams.
+ */
+
+declare(strict_types=1);
+
+namespace MongoDB\Examples;
+
+use MongoDB\BSON\ObjectId;
+use MongoDB\Client;
+
+use function assert;
+use function fclose;
+use function feof;
+use function fread;
+use function fwrite;
+use function getenv;
+use function strlen;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$client = new Client(getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/');
+// Disable MD5 computation for faster uploads, this feature is deprecated
+$bucket = $client->test->selectGridFSBucket(['disableMD5' => true]);
+
+// Open a stream for writing, similar to fopen with mode 'w'
+$stream = $bucket->openUploadStream('hello.txt');
+
+for ($i = 0; $i < 1_000_000; $i++) {
+    fwrite($stream, 'Hello line ' . $i . "\n");
+}
+
+// Last data are flushed to the server when the stream is closed
+fclose($stream);
+
+// Open a stream for reading, similar to fopen with mode 'r'
+$stream = $bucket->openDownloadStreamByName('hello.txt');
+
+$size = 0;
+while (! feof($stream)) {
+    $data = fread($stream, 2 ** 10);
+    $size += strlen($data);
+}
+
+echo 'Read a total of ' . $size . ' bytes' . "\n";
+
+// Retrieve the file ID to delete it
+$id = $bucket->getFileIdForStream($stream);
+assert($id instanceof ObjectId);
+$bucket->delete($id);
+
+echo 'Deleted file with ID: ' . $id . "\n";

examples/gridfs-stream-wrapper.php → examples/gridfs_stream_wrapper.php

@@ -18,42 +18,41 @@
 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();
+// Disable MD5 computation for faster uploads, this feature is deprecated
+$bucket = $client->test->selectGridFSBucket(['disableMD5' => true]);
 $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 "\n";
 
 echo 'Writing file';
 file_put_contents('gridfs://mybucket/hello.txt', 'Hello, GridFS!');
-echo PHP_EOL;
+echo "\n";
 
 echo 'File exists: ';
 echo file_exists('gridfs://mybucket/hello.txt') ? 'yes' : 'no';
-echo PHP_EOL;
+echo "\n";
 
 echo 'Reading file: ';
 echo file_get_contents('gridfs://mybucket/hello.txt');
-echo PHP_EOL;
+echo "\n";
 
 echo 'Writing new version of the file';
 file_put_contents('gridfs://mybucket/hello.txt', 'Hello, GridFS! (v2)');
-echo PHP_EOL;
+echo "\n";
 
 echo 'Reading new version of the file: ';
 echo file_get_contents('gridfs://mybucket/hello.txt');
-echo PHP_EOL;
+echo "\n";
 
 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;
+echo "\n";

examples/gridfs_upload.php

@@ -0,0 +1,49 @@
+<?php
+
+/**
+ * This example demonstrates how to upload and download files from a stream with GridFS.
+ */
+
+declare(strict_types=1);
+
+namespace MongoDB\Examples;
+
+use MongoDB\BSON\ObjectId;
+use MongoDB\Client;
+
+use function assert;
+use function fclose;
+use function fopen;
+use function fwrite;
+use function getenv;
+use function rewind;
+use function stream_get_contents;
+
+require __DIR__ . '/../vendor/autoload.php';
+
+$client = new Client(getenv('MONGODB_URI') ?: 'mongodb://127.0.0.1/');
+
+// Disable MD5 computation for faster uploads, this feature is deprecated
+$gridfs = $client->test->selectGridFSBucket(['disableMD5' => true]);
+
+// Create an in-memory stream, this can be any stream source like STDIN or php://input for web requests
+$stream = fopen('php://temp', 'w+');
+fwrite($stream, 'Hello world!');
+rewind($stream);
+
+// Upload to GridFS from the stream
+$id = $gridfs->uploadFromStream('hello.txt', $stream);
+assert($id instanceof ObjectId);
+echo 'Inserted file with ID: ', $id, "\n";
+fclose($stream);
+
+// Download the file and print the contents directly to an in-memory stream, chunk by chunk
+$stream = fopen('php://temp', 'w+');
+$gridfs->downloadToStreamByName('hello.txt', $stream);
+rewind($stream);
+echo 'File contents: ', stream_get_contents($stream), "\n";
+
+// Delete the file
+$gridfs->delete($id);
+
+echo 'Deleted file with ID: ', $id, "\n";

psalm-baseline.xml

@@ -5,7 +5,7 @@
       <code><![CDATA[$clientEncryption->decrypt($document->encryptedField)]]></code>
     </MixedArgument>
   </file>
-  <file src="examples/atlas-search.php">
+  <file src="examples/atlas_search.php">
     <MixedArgument>
       <code><![CDATA[$document['name']]]></code>
       <code><![CDATA[$index->name]]></code>

tests/ExamplesTest.php

@@ -99,6 +99,28 @@ public static function provideExamples(): Generator
             'expectedOutput' => $expectedOutput,
         ];
 
+        $expectedOutput = <<<'OUTPUT'
+Read a total of 17888890 bytes
+Deleted file with ID: %s
+OUTPUT;
+
+        yield 'gridfs_stream' => [
+            'file' => __DIR__ . '/../examples/gridfs_stream.php',
+            'expectedOutput' => $expectedOutput,
+        ];
+
+        $expectedOutput = <<<'OUTPUT'
+Inserted file with ID: %s
+File contents: Hello world!
+Deleted file with ID: %s
+
+OUTPUT;
+
+        yield 'gridfs_upload' => [
+            'file' => __DIR__ . '/../examples/gridfs_upload.php',
+            'expectedOutput' => $expectedOutput,
+        ];
+
         $expectedOutput = <<<'OUTPUT'
 File exists: no
 Writing file
@@ -109,8 +131,8 @@ public static function provideExamples(): Generator
 Reading previous version of the file: Hello, GridFS!
 OUTPUT;
 
-        yield 'gridfs-stream-wrapper' => [
-            'file' => __DIR__ . '/../examples/gridfs-stream-wrapper.php',
+        yield 'gridfs_stream_wrapper' => [
+            'file' => __DIR__ . '/../examples/gridfs_stream_wrapper.php',
             'expectedOutput' => $expectedOutput,
         ];
 
@@ -243,7 +265,7 @@ public function testAtlasSearch(): void
 
 OUTPUT;
 
-        $this->assertExampleOutput(__DIR__ . '/../examples/atlas-search.php', $expectedOutput);
+        $this->assertExampleOutput(__DIR__ . '/../examples/atlas_search.php', $expectedOutput);
     }
 
     public function testChangeStream(): void