Generate PutBucketTagging method for s3 client (#1451)

generate PutBucketTagging method for s3 client

Author: nealio82

docs/clients/s3.md

@@ -104,6 +104,32 @@ foreach ($result->getBody()->getChunks() as $chunk) {
 }
 ```
 
+### Add tags to a bucket
+
+You can add tags to your buckets to help you find related resources in the AWS cost explorer; eg all AWS resources tagged
+with `environment = staging` would show you the amount you're spending on your pre-prod environment each month
+
+```
+$client->putBucketTagging(
+    new PutBucketTaggingRequest([
+        'Bucket' => 'my-website-assets-bucket',
+
+        'Tagging' => new Tagging([
+            'TagSet' => [
+                new Tag([
+                    'Key' => 'environment',
+                    'Value' => 'production',
+                ]),
+                new Tag([
+                    'Key' => 'project-name',
+                    'Value' => 'unicorn',
+                ])
+            ],
+        ]),
+    ])
+);
+```
+
 ## Virtual Hosted-Style Requests
 
 When calling AWS endpoints, AsyncAws uses [Virtual Hosted-Style Requests](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html):

manifest.json

@@ -554,6 +554,7 @@
                 "ObjectNotExists",
                 "PutBucketCors",
                 "PutBucketNotificationConfiguration",
+                "PutBucketTagging",
                 "PutObject",
                 "PutObjectAcl",
                 "UploadPart"

src/Service/S3/src/Input/PutBucketTaggingRequest.php

@@ -0,0 +1,212 @@
+<?php
+
+namespace AsyncAws\S3\Input;
+
+use AsyncAws\Core\Exception\InvalidArgument;
+use AsyncAws\Core\Input;
+use AsyncAws\Core\Request;
+use AsyncAws\Core\Stream\StreamFactory;
+use AsyncAws\S3\Enum\ChecksumAlgorithm;
+use AsyncAws\S3\ValueObject\Tag;
+use AsyncAws\S3\ValueObject\Tagging;
+
+final class PutBucketTaggingRequest extends Input
+{
+    /**
+     * The bucket name.
+     *
+     * @required
+     *
+     * @var string|null
+     */
+    private $bucket;
+
+    /**
+     * The base64-encoded 128-bit MD5 digest of the data. You must use this header as a message integrity check to verify
+     * that the request body was not corrupted in transit. For more information, see RFC 1864 [^1].
+     *
+     * For requests made using the Amazon Web Services Command Line Interface (CLI) or Amazon Web Services SDKs, this field
+     * is calculated automatically.
+     *
+     * [^1]: http://www.ietf.org/rfc/rfc1864.txt
+     *
+     * @var string|null
+     */
+    private $contentMd5;
+
+    /**
+     * Indicates the algorithm used to create the checksum for the object when using the SDK. This header will not provide
+     * any additional functionality if not using the SDK. When sending this header, there must be a corresponding
+     * `x-amz-checksum` or `x-amz-trailer` header sent. Otherwise, Amazon S3 fails the request with the HTTP status code
+     * `400 Bad Request`. For more information, see Checking object integrity [^1] in the *Amazon S3 User Guide*.
+     *
+     * If you provide an individual checksum, Amazon S3 ignores any provided `ChecksumAlgorithm` parameter.
+     *
+     * [^1]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/checking-object-integrity.html
+     *
+     * @var ChecksumAlgorithm::*|null
+     */
+    private $checksumAlgorithm;
+
+    /**
+     * Container for the `TagSet` and `Tag` elements.
+     *
+     * @required
+     *
+     * @var Tagging|null
+     */
+    private $tagging;
+
+    /**
+     * The account ID of the expected bucket owner. If the bucket is owned by a different account, the request fails with
+     * the HTTP status code `403 Forbidden` (access denied).
+     *
+     * @var string|null
+     */
+    private $expectedBucketOwner;
+
+    /**
+     * @param array{
+     *   Bucket?: string,
+     *   ContentMD5?: string,
+     *   ChecksumAlgorithm?: ChecksumAlgorithm::*,
+     *   Tagging?: Tagging|array,
+     *   ExpectedBucketOwner?: string,
+     *
+     *   @region?: string,
+     * } $input
+     */
+    public function __construct(array $input = [])
+    {
+        $this->bucket = $input['Bucket'] ?? null;
+        $this->contentMd5 = $input['ContentMD5'] ?? null;
+        $this->checksumAlgorithm = $input['ChecksumAlgorithm'] ?? null;
+        $this->tagging = isset($input['Tagging']) ? Tagging::create($input['Tagging']) : null;
+        $this->expectedBucketOwner = $input['ExpectedBucketOwner'] ?? null;
+        parent::__construct($input);
+    }
+
+    public static function create($input): self
+    {
+        return $input instanceof self ? $input : new self($input);
+    }
+
+    public function getBucket(): ?string
+    {
+        return $this->bucket;
+    }
+
+    /**
+     * @return ChecksumAlgorithm::*|null
+     */
+    public function getChecksumAlgorithm(): ?string
+    {
+        return $this->checksumAlgorithm;
+    }
+
+    public function getContentMd5(): ?string
+    {
+        return $this->contentMd5;
+    }
+
+    public function getExpectedBucketOwner(): ?string
+    {
+        return $this->expectedBucketOwner;
+    }
+
+    public function getTagging(): ?Tagging
+    {
+        return $this->tagging;
+    }
+
+    /**
+     * @internal
+     */
+    public function request(): Request
+    {
+        // Prepare headers
+        $headers = ['content-type' => 'application/xml'];
+        if (null !== $this->contentMd5) {
+            $headers['Content-MD5'] = $this->contentMd5;
+        }
+        if (null !== $this->checksumAlgorithm) {
+            if (!ChecksumAlgorithm::exists($this->checksumAlgorithm)) {
+                throw new InvalidArgument(sprintf('Invalid parameter "ChecksumAlgorithm" for "%s". The value "%s" is not a valid "ChecksumAlgorithm".', __CLASS__, $this->checksumAlgorithm));
+            }
+            $headers['x-amz-sdk-checksum-algorithm'] = $this->checksumAlgorithm;
+        }
+        if (null !== $this->expectedBucketOwner) {
+            $headers['x-amz-expected-bucket-owner'] = $this->expectedBucketOwner;
+        }
+
+        // Prepare query
+        $query = [];
+
+        // Prepare URI
+        $uri = [];
+        if (null === $v = $this->bucket) {
+            throw new InvalidArgument(sprintf('Missing parameter "Bucket" for "%s". The value cannot be null.', __CLASS__));
+        }
+        $uri['Bucket'] = $v;
+        $uriString = '/' . rawurlencode($uri['Bucket']) . '?tagging';
+
+        // Prepare Body
+
+        $document = new \DOMDocument('1.0', 'UTF-8');
+        $document->formatOutput = false;
+        $this->requestBody($document, $document);
+        $body = $document->hasChildNodes() ? $document->saveXML() : '';
+
+        // Return the Request
+        return new Request('PUT', $uriString, $query, $headers, StreamFactory::create($body));
+    }
+
+    public function setBucket(?string $value): self
+    {
+        $this->bucket = $value;
+
+        return $this;
+    }
+
+    /**
+     * @param ChecksumAlgorithm::*|null $value
+     */
+    public function setChecksumAlgorithm(?string $value): self
+    {
+        $this->checksumAlgorithm = $value;
+
+        return $this;
+    }
+
+    public function setContentMd5(?string $value): self
+    {
+        $this->contentMd5 = $value;
+
+        return $this;
+    }
+
+    public function setExpectedBucketOwner(?string $value): self
+    {
+        $this->expectedBucketOwner = $value;
+
+        return $this;
+    }
+
+    public function setTagging(?Tagging $value): self
+    {
+        $this->tagging = $value;
+
+        return $this;
+    }
+
+    private function requestBody(\DOMNode $node, \DOMDocument $document): void
+    {
+        if (null === $v = $this->tagging) {
+            throw new InvalidArgument(sprintf('Missing parameter "Tagging" for "%s". The value cannot be null.', __CLASS__));
+        }
+
+        $node->appendChild($child = $document->createElement('Tagging'));
+        $child->setAttribute('xmlns', 'http://s3.amazonaws.com/doc/2006-03-01/');
+        $v->requestBody($child, $document);
+    }
+}

src/Service/S3/src/S3Client.php

@@ -49,6 +49,7 @@
 use AsyncAws\S3\Input\ListPartsRequest;
 use AsyncAws\S3\Input\PutBucketCorsRequest;
 use AsyncAws\S3\Input\PutBucketNotificationConfigurationRequest;
+use AsyncAws\S3\Input\PutBucketTaggingRequest;
 use AsyncAws\S3\Input\PutObjectAclRequest;
 use AsyncAws\S3\Input\PutObjectRequest;
 use AsyncAws\S3\Input\UploadPartRequest;
@@ -84,6 +85,7 @@
 use AsyncAws\S3\ValueObject\MultipartUpload;
 use AsyncAws\S3\ValueObject\NotificationConfiguration;
 use AsyncAws\S3\ValueObject\Part;
+use AsyncAws\S3\ValueObject\Tagging;
 
 class S3Client extends AbstractApi
 {
@@ -1832,6 +1834,81 @@ public function putBucketNotificationConfiguration($input): Result
         return new Result($response);
     }
 
+    /**
+     * Sets the tags for a bucket.
+     *
+     * Use tags to organize your Amazon Web Services bill to reflect your own cost structure. To do this, sign up to get
+     * your Amazon Web Services account bill with tag key values included. Then, to see the cost of combined resources,
+     * organize your billing information according to resources with the same tag key values. For example, you can tag
+     * several resources with a specific application name, and then organize your billing information to see the total cost
+     * of that application across several services. For more information, see Cost Allocation and Tagging [^1] and Using
+     * Cost Allocation in Amazon S3 Bucket Tags [^2].
+     *
+     * > When this operation sets the tags for a bucket, it will overwrite any current tags the bucket already has. You
+     * > cannot use this operation to add tags to an existing list of tags.
+     *
+     * To use this operation, you must have permissions to perform the `s3:PutBucketTagging` action. The bucket owner has
+     * this permission by default and can grant this permission to others. For more information about permissions, see
+     * Permissions Related to Bucket Subresource Operations [^3] and Managing Access Permissions to Your Amazon S3 Resources
+     * [^4].
+     *
+     * `PutBucketTagging` has the following special errors:
+     *
+     * - Error code: `InvalidTagError`
+     *
+     *   - Description: The tag provided was not a valid tag. This error can occur if the tag did not pass input validation.
+     *     For information about tag restrictions, see User-Defined Tag Restrictions [^5] and Amazon Web Services-Generated
+     *     Cost Allocation Tag Restrictions [^6].
+     *
+     * - Error code: `MalformedXMLError`
+     *
+     *   - Description: The XML provided does not match the schema.
+     *
+     * - Error code: `OperationAbortedError `
+     *
+     *   - Description: A conflicting conditional action is currently in progress against this resource. Please try again.
+     *
+     * - Error code: `InternalError`
+     *
+     *   - Description: The service was unable to apply the provided tag to the bucket.
+     *
+     *
+     * The following operations are related to `PutBucketTagging`:
+     *
+     * - GetBucketTagging [^7]
+     * - DeleteBucketTagging [^8]
+     *
+     * [^1]: https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/cost-alloc-tags.html
+     * [^2]: https://docs.aws.amazon.com/AmazonS3/latest/dev/CostAllocTagging.html
+     * [^3]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-actions.html#using-with-s3-actions-related-to-bucket-subresources
+     * [^4]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html
+     * [^5]: https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/allocation-tag-restrictions.html
+     * [^6]: https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/aws-tag-restrictions.html
+     * [^7]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketTagging.html
+     * [^8]: https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucketTagging.html
+     *
+     * @see http://docs.amazonwebservices.com/AmazonS3/latest/API/RESTBucketPUTtagging.html
+     * @see https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutBucketTagging.html
+     * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html#putbuckettagging
+     *
+     * @param array{
+     *   Bucket: string,
+     *   ContentMD5?: string,
+     *   ChecksumAlgorithm?: ChecksumAlgorithm::*,
+     *   Tagging: Tagging|array,
+     *   ExpectedBucketOwner?: string,
+     *
+     *   @region?: string,
+     * }|PutBucketTaggingRequest $input
+     */
+    public function putBucketTagging($input): Result
+    {
+        $input = PutBucketTaggingRequest::create($input);
+        $response = $this->getResponse($input->request(), new RequestContext(['operation' => 'PutBucketTagging', 'region' => $input->getRegion()]));
+
+        return new Result($response);
+    }
+
     /**
      * Adds an object to a bucket. You must have WRITE permissions on a bucket to add an object to it.
      *