feat: doesObjectExist and doesBucketExist v2

src/S3/S3ClientInterface.php

@@ -48,6 +48,17 @@ public function getObjectUrl($bucket, $key);
      */
     public function doesBucketExist($bucket);
 
+    /**
+     * Determines whether or not a bucket exists by name.
+     *
+     * @param string $bucket  The name of the bucket
+     * @param bool $accept403 Changes behavior to return true in the case of a 403.
+     *                        credentials MUST be correct to avoid inaccuracies.
+     *
+     * @return bool
+     */
+    public function doesBucketExistV2($bucket, $accept403);
+
     /**
      * Determines whether or not an object exists by name.
      *
@@ -60,6 +71,20 @@ public function doesBucketExist($bucket);
      */
     public function doesObjectExist($bucket, $key, array $options = []);
 
+    /**
+     * Determines whether or not an object exists by name.
+     *
+     * @param string $bucket The name of the bucket
+     * @param string $key The key of the object
+     * @param bool $includeDeleteMarkers Optional flag that will consider delete markers
+     *                                   existing objects
+     * @param array $options Additional options available in the HeadObject
+     *                        operation (e.g., VersionId).
+     *
+     * @return bool
+     */
+    public function doesObjectExistV2($bucket, $key, $includeDeleteMarkers, array $options = []);
+
     /**
      * Register the Amazon S3 stream wrapper with this client instance.
      */

src/S3/S3ClientTrait.php

@@ -6,6 +6,7 @@
 use Aws\Exception\AwsException;
 use Aws\HandlerList;
 use Aws\ResultInterface;
+use Aws\S3\Exception\PermanentRedirectException;
 use Aws\S3\Exception\S3Exception;
 use GuzzleHttp\Promise\PromiseInterface;
 use GuzzleHttp\Promise\RejectedPromise;
@@ -260,6 +261,17 @@ public function doesBucketExist($bucket)
         );
     }
 
+    /**
+     * @see S3ClientInterface::doesBucketExistV2()
+     */
+    public function doesBucketExistV2($bucket, $accept403 = false)
+    {
+        return $this->checkExistenceWithCommandV2(
+            $this->getCommand('HeadBucket', ['Bucket' => $bucket]),
+            $accept403
+        );
+    }
+
     /**
      * @see S3ClientInterface::doesObjectExist()
      */
@@ -273,6 +285,27 @@ public function doesObjectExist($bucket, $key, array $options = [])
         );
     }
 
+    /**
+     * @see S3ClientInterface::doesObjectExistV2()
+     */
+    public function doesObjectExistV2(
+        $bucket,
+        $key,
+        $includeDeleteMarkers = false,
+        array $options = []
+    )
+    {
+        return $this->checkExistenceWithCommandV2(
+            $this->getCommand('HeadObject', [
+                    'Bucket' => $bucket,
+                    'Key'    => $key
+                ] + $options
+            ),
+            false,
+            $includeDeleteMarkers
+        );
+    }
+
     /**
      * Determines whether or not a resource exists using a command
      *
@@ -297,6 +330,42 @@ private function checkExistenceWithCommand(CommandInterface $command)
         }
     }
 
+    /**
+     * Determines whether or not a resource exists using a command
+     *
+     * @param CommandInterface $command Command used to poll for the resource
+     * @param bool $accept403 Optional argument that changes exception handling behavior
+     * @param bool $includeDeleteMarkers Optional argument will count delete markers as existing objects
+     *
+     * @return bool
+     * @throws S3Exception|Exception if there is an unhandled exception
+     */
+    private function checkExistenceWithCommandV2(
+        CommandInterface $command,
+        $accept403,
+        $includeDeleteMarkers = false
+    )
+    {
+        try {
+            $this->execute($command);
+            return true;
+        } catch (S3Exception $e) {
+            if (($accept403 && $e->getStatusCode() === 403)
+                || (!empty($e->getResponse()->getHeaders()["x-amz-delete-marker"])
+                    && $includeDeleteMarkers)
+                || ($command->getName() === 'HeadBucket'
+                    && $e instanceof PermanentRedirectException)
+                )
+            {
+                return true;
+            }
+            if ($e->getStatusCode() === 404) {
+                return false;
+            }
+            throw $e;
+        }
+    }
+
     /**
      * @see S3ClientInterface::execute()
      */

tests/S3/S3ClientTest.php

@@ -9,6 +9,7 @@
 use Aws\Endpoint\PartitionEndpointProvider;
 use Aws\Middleware;
 use Aws\Result;
+use Aws\S3\Exception\PermanentRedirectException;
 use Aws\S3\Exception\S3Exception;
 use Aws\S3\RegionalEndpoint\Configuration;
 use Aws\S3\S3Client;
@@ -232,6 +233,13 @@ public function testRegistersStreamWrapper()
 
     public function doesExistProvider()
     {
+        $redirectException = new PermanentRedirectException(
+            '',
+            new Command('mockCommand'),
+            ['response' => new Response(301)]
+        );
+        $deleteMarkerMock = $this->getS3ErrorMock('Foo', 404, true);
+
         return [
             ['foo', null, true, []],
             ['foo', 'bar', true, []],
@@ -241,31 +249,60 @@ public function doesExistProvider()
             ['foo', 'bar', false, $this->getS3ErrorMock('Foo', 401)],
             ['foo', null, -1, $this->getS3ErrorMock('Foo', 500)],
             ['foo', 'bar', -1, $this->getS3ErrorMock('Foo', 500)],
+            ['foo', null, true, [], true],
+            ['foo', 'bar', true, [] , true],
+            ['foo', null, false, $this->getS3ErrorMock('Foo', 404), true],
+            ['foo', 'bar', false, $this->getS3ErrorMock('Foo', 404), true],
+            ['foo', null, -1, $this->getS3ErrorMock('Forbidden', 403), true],
+            ['foo', 'bar', -1, $this->getS3ErrorMock('Forbidden', 403), true],
+            ['foo', null, true, $this->getS3ErrorMock('Forbidden', 403), true, true],
+            ['foo', 'bar', true, $deleteMarkerMock, true, false, true],
+            ['foo', 'bar', false, $deleteMarkerMock, true, false, false],
+            ['foo', null, true, $redirectException, true],
         ];
     }
 
-    private function getS3ErrorMock($errCode, $statusCode)
+    private function getS3ErrorMock($errCode, $statusCode, $deleteMarker = false)
     {
+        $response = new Response($statusCode);
+        $deleteMarker && $response = $response->withHeader('x-amz-delete-marker', true);
+
         $context = [
             'code' => $errCode,
-            'response' => new Response($statusCode),
+            'response' => $response,
         ];
         return new S3Exception('', new Command('mockCommand'), $context);
     }
 
     /**
      * @dataProvider doesExistProvider
      */
-    public function testsIfExists($bucket, $key, $exists, $result)
+    public function testsIfExists(
+        $bucket,
+        $key,
+        $exists,
+        $result,
+        $V2 = false,
+        $accept403 = false,
+        $acceptDeleteMarkers = false
+    )
     {
         /** @var S3Client $s3 */
         $s3 = $this->getTestClient('S3', ['region' => 'us-east-1']);
         $this->addMockResults($s3, [$result]);
         try {
-            if ($key) {
-                $this->assertSame($exists, $s3->doesObjectExist($bucket, $key));
-            } else {
-                $this->assertSame($exists, $s3->doesBucketExist($bucket));
+            if ($V2) {
+                if ($key) {
+                    $this->assertSame($exists, $s3->doesObjectExistV2($bucket, $key, $acceptDeleteMarkers));
+                } else {
+                    $this->assertSame($exists, $s3->doesBucketExistV2($bucket, $accept403));
+                }
+            }else {
+                if ($key) {
+                    $this->assertSame($exists, $s3->doesObjectExist($bucket, $key));
+                } else {
+                    $this->assertSame($exists, $s3->doesBucketExist($bucket));
+                }
             }
         } catch (\Exception $e) {
             $this->assertSame(-1, $exists);
@@ -278,7 +315,10 @@ public function testReturnsObjectUrl()
             'region'      => 'us-east-1',
             'credentials' => false
         ]);
-        $this->assertSame('https://foo.s3.amazonaws.com/bar', $s3->getObjectUrl('foo', 'bar'));
+        $this->assertSame(
+            'https://foo.s3.amazonaws.com/bar',
+            $s3->getObjectUrl('foo', 'bar')
+        );
     }
 
     public function testReturnsObjectUrlWithPathStyleFallback()
@@ -287,7 +327,10 @@ public function testReturnsObjectUrlWithPathStyleFallback()
             'region'      => 'us-east-1',
             'credentials' => false,
         ]);
-        $this->assertSame('https://s3.amazonaws.com/foo.baz/bar', $s3->getObjectUrl('foo.baz', 'bar'));
+        $this->assertSame(
+            'https://s3.amazonaws.com/foo.baz/bar',
+            $s3->getObjectUrl('foo.baz', 'bar')
+        );
     }
 
     public function testReturnsObjectUrlWithPathStyle()
@@ -297,7 +340,10 @@ public function testReturnsObjectUrlWithPathStyle()
             'credentials' => false,
             'use_path_style_endpoint' => true
         ]);
-        $this->assertSame('https://s3.amazonaws.com/foo/bar', $s3->getObjectUrl('foo', 'bar'));
+        $this->assertSame(
+            'https://s3.amazonaws.com/foo/bar',
+            $s3->getObjectUrl('foo', 'bar')
+        );
     }
 
     public function testReturnsObjectUrlViaPath()