Deprecate not setting disableMD5 to true when using GridFS

Author: GromNaN

UPGRADE-1.18.md

@@ -0,0 +1,11 @@
+# UPGRADE FROM 1.x to 1.18
+
+## Required options
+
+### GridFS disableMD5 option must be true
+
+Starting with 1.18, not passing the `disableMD5` option to `Database::getGridFSBucket()`
+is deprecated. You should explicitly pass `true` to this option to disable
+checksum computation. This feature is deprecated in the GridFS specification.
+In the next major version, the default value will be `true` and an exception
+will be thrown if you set it to another value.

src/GridFS/Bucket.php

@@ -58,8 +58,11 @@
 use function stream_copy_to_stream;
 use function stream_get_meta_data;
 use function stream_get_wrappers;
+use function trigger_error;
 use function urlencode;
 
+use const E_USER_DEPRECATED;
+
 /**
  * Bucket provides a public API for interacting with the GridFS files and chunks
  * collections.
@@ -112,7 +115,8 @@ class Bucket
      *    261120 (i.e. 255 KiB).
      *
      *  * disableMD5 (boolean): When true, no MD5 sum will be generated for
-     *    each stored file. Defaults to "false".
+     *    each stored file. Defaults to "false", will be "true" in the next
+     *    major version.
      *
      *  * readConcern (MongoDB\Driver\ReadConcern): Read concern.
      *
@@ -155,6 +159,10 @@ public function __construct(Manager $manager, string $databaseName, array $optio
             throw InvalidArgumentException::invalidType('"disableMD5" option', $options['disableMD5'], 'boolean');
         }
 
+        if (! $options['disableMD5']) {
+            @trigger_error('Not setting "disableMD5" option to "true" is deprecated. Checksum is deprecated by GridFS spec and will be removed in mongodb/mongodb 2.0', E_USER_DEPRECATED);
+        }
+
         if (isset($options['readConcern']) && ! $options['readConcern'] instanceof ReadConcern) {
             throw InvalidArgumentException::invalidType('"readConcern" option', $options['readConcern'], ReadConcern::class);
         }

tests/GridFS/BucketFunctionalTest.php

@@ -2,6 +2,7 @@
 
 namespace MongoDB\Tests\GridFS;
 
+use Generator;
 use MongoDB\BSON\Binary;
 use MongoDB\Collection;
 use MongoDB\Driver\ReadConcern;
@@ -19,6 +20,7 @@
 use MongoDB\Tests\Fixtures\Codec\TestFileCodec;
 use MongoDB\Tests\Fixtures\Document\TestFile;
 use stdClass;
+use Symfony\Bridge\PhpUnit\ExpectDeprecationTrait;
 
 use function array_merge;
 use function call_user_func;
@@ -48,6 +50,8 @@
  */
 class BucketFunctionalTest extends FunctionalTestCase
 {
+    use ExpectDeprecationTrait;
+
     /** @doesNotPerformAssertions */
     public function testValidConstructorOptions(): void
     {
@@ -86,14 +90,15 @@ public function testConstructorShouldRequireChunkSizeBytesOptionToBePositive():
     {
         $this->expectException(InvalidArgumentException::class);
         $this->expectExceptionMessage('Expected "chunkSizeBytes" option to be >= 1, 0 given');
-        new Bucket($this->manager, $this->getDatabaseName(), ['chunkSizeBytes' => 0]);
+        new Bucket($this->manager, $this->getDatabaseName(), ['chunkSizeBytes' => 0, 'disableMD5' => true]);
     }
 
     public function testConstructorWithCodecAndTypeMapOptions(): void
     {
         $options = [
             'codec' => new TestDocumentCodec(),
             'typeMap' => ['root' => 'array', 'document' => 'array'],
+            'disableMD5' => true,
         ];
 
         $this->expectExceptionObject(InvalidArgumentException::cannotCombineCodecAndTypeMap());
@@ -347,7 +352,10 @@ public function testFindUsesCodec(): void
 
     public function testFindInheritsBucketCodec(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['codec' => new TestFileCodec()]);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'codec' => new TestFileCodec(),
+            'disableMD5' => true,
+        ]);
         $bucket->uploadFromStream('a', $this->createStream('foo'));
 
         $cursor = $bucket->find();
@@ -359,7 +367,10 @@ public function testFindInheritsBucketCodec(): void
 
     public function testFindResetsInheritedBucketCodec(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['codec' => new TestFileCodec()]);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'codec' => new TestFileCodec(),
+            'disableMD5' => true,
+        ]);
         $bucket->uploadFromStream('a', $this->createStream('foo'));
 
         $cursor = $bucket->find([], ['codec' => null]);
@@ -412,7 +423,10 @@ public function testFindOneUsesCodec(): void
 
     public function testFindOneInheritsBucketCodec(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['codec' => new TestFileCodec()]);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'codec' => new TestFileCodec(),
+            'disableMD5' => true,
+        ]);
 
         $bucket->uploadFromStream('a', $this->createStream('foo'));
         $bucket->uploadFromStream('b', $this->createStream('foobar'));
@@ -430,7 +444,10 @@ public function testFindOneInheritsBucketCodec(): void
 
     public function testFindOneResetsInheritedBucketCodec(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['codec' => new TestFileCodec()]);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'codec' => new TestFileCodec(),
+            'disableMD5' => true,
+        ]);
 
         $bucket->uploadFromStream('a', $this->createStream('foo'));
         $bucket->uploadFromStream('b', $this->createStream('foobar'));
@@ -451,7 +468,10 @@ public function testFindOneResetsInheritedBucketCodec(): void
 
     public function testGetBucketNameWithCustomValue(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['bucketName' => 'custom_fs']);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'bucketName' => 'custom_fs',
+            'disableMD5' => true,
+        ]);
 
         $this->assertEquals('custom_fs', $bucket->getBucketName());
     }
@@ -471,7 +491,10 @@ public function testGetChunksCollection(): void
 
     public function testGetChunkSizeBytesWithCustomValue(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['chunkSizeBytes' => 8192]);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'chunkSizeBytes' => 8192,
+            'disableMD5' => true,
+        ]);
 
         $this->assertEquals(8192, $bucket->getChunkSizeBytes());
     }
@@ -500,7 +523,10 @@ public function testGetFileDocumentForStreamUsesTypeMap(): void
 
     public function testGetFileDocumentForStreamUsesCodec(): void
     {
-        $bucket = new Bucket($this->manager, $this->getDatabaseName(), ['codec' => new TestFileCodec()]);
+        $bucket = new Bucket($this->manager, $this->getDatabaseName(), [
+            'codec' => new TestFileCodec(),
+            'disableMD5' => true,
+        ]);
 
         $metadata = ['foo' => 'bar'];
         $stream = $bucket->openUploadStream('filename', ['_id' => 1, 'metadata' => $metadata]);
@@ -799,6 +825,23 @@ public function testDisableMD5OptionInConstructor(): void
         $this->assertArrayNotHasKey('md5', $fileDocument);
     }
 
+    /**
+     * @dataProvider provideDeprecatedDisableMD5Options
+     * @group legacy
+     */
+    public function testNotDisablingMD5IsDeprecated(array $options): void
+    {
+        $this->expectDeprecation('Not setting "disableMD5" option to "true" is deprecated. Checksum is deprecated by GridFS spec and will be removed in mongodb/mongodb 2.0');
+
+        new Bucket($this->manager, $this->getDatabaseName(), $options);
+    }
+
+    public static function provideDeprecatedDisableMD5Options(): Generator
+    {
+        yield 'set to false' => [['disableMD5' => false]];
+        yield 'not set' => [[]];
+    }
+
     public function testUploadingFirstFileCreatesIndexes(): void
     {
         $this->bucket->uploadFromStream('filename', $this->createStream('foo'));
@@ -859,7 +902,7 @@ public function testDanglingOpenWritableStream(): void
             require '%s';
             $client = MongoDB\Tests\FunctionalTestCase::createTestClient();
             $database = $client->selectDatabase(getenv('MONGODB_DATABASE') ?: 'phplib_test');
-            $gridfs = $database->selectGridFSBucket();
+            $gridfs = $database->selectGridFSBucket(['disableMD5' => true]);
             $stream = $gridfs->openUploadStream('hello.txt', ['disableMD5' => true]);
             fwrite($stream, 'Hello MongoDB!');
             PHP;

tests/GridFS/FunctionalTestCase.php

@@ -27,7 +27,7 @@ public function setUp(): void
     {
         parent::setUp();
 
-        $this->bucket = new Bucket($this->manager, $this->getDatabaseName());
+        $this->bucket = new Bucket($this->manager, $this->getDatabaseName(), ['disableMD5' => true]);
         $this->bucket->drop();
 
         $this->chunksCollection = $this->createCollection($this->getDatabaseName(), 'fs.chunks');