fix: allow configuring retain_visibility on a filesystem

Author: rvanlaak

docs/2-cloud-storage-providers.md

@@ -161,7 +161,7 @@ flysystem:
 ## Cloudflare R2
 
 The Cloudflare R2 is compatible with the AWS S3 API, meaning that you can use the same configuration
-as for an AWS storage. For example:
+as for an AWS storage. Both the regular and the async AWS Client can be used. As example:
 
 ```yaml
 # config/packages/flysystem.yaml
@@ -184,6 +184,23 @@ flysystem:
                 bucket: '%env(CLOUDFLARE_R2_BUCKET)%'
 ```
 
+Cloudflare R2 does not have implemented ACL-related features yet, and thereby making use of Flysystem's `move` and `copy` 
+methods requires configuring explicit value for `visibility` and setting `retain_visibility` to `false` to prevent the 
+S3 adapter to call the `GetObjectAcl` command to retrieve an object's current ACL visibility, then resulting in an exception.
+
+```yaml
+flysystem:
+    storages:
+        cdn.storage:
+            # ...
+            visibility: private # or public
+            
+            # to use the visibility as defined above instead of retaining the object's visibility, and not having to run
+            # the unsupported `GetObjectAcl` command to get the object's current visibility.
+            retain_visibility: false  
+            # ...
+```
+
 ## Next
 
 [Interacting with FTP and SFTP servers](https://github.com/thephpleague/flysystem-bundle/blob/master/docs/3-interacting-with-ftp-and-sftp-servers.md)

src/DependencyInjection/Configuration.php

@@ -42,7 +42,7 @@ public function getConfigTreeBuilder(): TreeBuilder
                             ->end()
                             ->scalarNode('visibility')->defaultNull()->end()
                             ->scalarNode('directory_visibility')->defaultNull()->end()
-                            ->booleanNode('retain_visibility')->defaultTrue()->end()
+                            ->booleanNode('retain_visibility')->defaultNull()->end()
                             ->booleanNode('case_sensitive')->defaultTrue()->end()
                             ->booleanNode('disable_asserts')->defaultFalse()->end()
                             ->arrayNode('public_url')

tests/DependencyInjection/FlysystemExtensionTest.php

@@ -15,6 +15,7 @@
 use Aws\S3\S3Client;
 use Google\Cloud\Storage\Bucket;
 use Google\Cloud\Storage\StorageClient;
+use League\Flysystem\Filesystem;
 use League\Flysystem\FilesystemOperator;
 use League\Flysystem\UnableToWriteFile;
 use MicrosoftAzure\Storage\Blob\BlobRestProxy;
@@ -118,6 +119,28 @@ public function testReadOnly(): void
         $fs->write('/path/to/file', 'Unable to write in read only');
     }
 
+    public function testNotRetainingVisibilityPreventsAclCommandInvocation(): void
+    {
+        $kernel = $this->createFlysystemKernel();
+        $container = $kernel->getContainer()->get('test.service_container');
+
+        $calledGetObjectAcl = false;
+
+        /** @var S3Client $mock */
+        $mock = $container->get('aws_client_service');
+        $mock->method('getCommand')->with($this->callback(function ($name) use (&$calledGetObjectAcl) {
+            if ('GetObjectAcl' === $name) {
+                $calledGetObjectAcl = true;
+            }
+        }));
+
+        /** @var Filesystem $fs */
+        $fs = $container->get('flysystem.test.fs_aws');
+        $fs->copy('test.txt', 'test2.txt');
+
+        self::assertFalse($calledGetObjectAcl, 'The ACL command should not be called when `retain_visibility` is set to `false`.');
+    }
+
     private function createFlysystemKernel(): FlysystemAppKernel
     {
         (new Dotenv())->populate([

tests/Kernel/config/flysystem.php

@@ -15,6 +15,8 @@
             ],
             'fs_aws' => [
                 'adapter' => 'aws',
+                'visibility' => 'private',
+                'retain_visibility' => false,
                 'options' => [
                     'client' => 'aws_client_service',
                     'bucket' => '%env(AWS_BUCKET)%',