vendor/aws/aws-sdk-php/src/S3/S3Client.php line 384

Open in your IDE?
  1. <?php
  2. namespace Aws\S3;
  4. use Aws\Api\ApiProvider;
  5. use Aws\Api\DocModel;
  6. use Aws\Api\Service;
  7. use Aws\AwsClient;
  8. use Aws\CacheInterface;
  9. use Aws\ClientResolver;
  10. use Aws\Command;
  11. use Aws\CommandInterface;
  12. use Aws\Configuration\ConfigurationResolver;
  13. use Aws\Exception\AwsException;
  14. use Aws\HandlerList;
  15. use Aws\Identity\S3\S3ExpressIdentityProvider;
  16. use Aws\InputValidationMiddleware;
  17. use Aws\Middleware;
  18. use Aws\ResultInterface;
  19. use Aws\Retry\QuotaManager;
  20. use Aws\RetryMiddleware;
  21. use Aws\RetryMiddlewareV2;
  22. use Aws\S3\Parser\GetBucketLocationResultMutator;
  23. use Aws\S3\Parser\S3Parser;
  24. use Aws\S3\Parser\ValidateResponseChecksumResultMutator;
  25. use Aws\S3\RegionalEndpoint\ConfigurationProvider;
  26. use Aws\S3\UseArnRegion\Configuration;
  27. use Aws\S3\UseArnRegion\ConfigurationInterface;
  28. use Aws\S3\UseArnRegion\ConfigurationProvider as UseArnRegionConfigurationProvider;
  29. use GuzzleHttp\Exception\RequestException;
  30. use GuzzleHttp\Promise\PromiseInterface;
  31. use Psr\Http\Message\RequestInterface;
  33. /**
  34.  * Client used to interact with **Amazon Simple Storage Service (Amazon S3)**.
  35.  *
  36.  * @method \Aws\Result abortMultipartUpload(array $args = [])
  37.  * @method \GuzzleHttp\Promise\Promise abortMultipartUploadAsync(array $args = [])
  38.  * @method \Aws\Result completeMultipartUpload(array $args = [])
  39.  * @method \GuzzleHttp\Promise\Promise completeMultipartUploadAsync(array $args = [])
  40.  * @method \Aws\Result copyObject(array $args = [])
  41.  * @method \GuzzleHttp\Promise\Promise copyObjectAsync(array $args = [])
  42.  * @method \Aws\Result createBucket(array $args = [])
  43.  * @method \GuzzleHttp\Promise\Promise createBucketAsync(array $args = [])
  44.  * @method \Aws\Result createMultipartUpload(array $args = [])
  45.  * @method \GuzzleHttp\Promise\Promise createMultipartUploadAsync(array $args = [])
  46.  * @method \Aws\Result createSession(array $args = [])
  47.  * @method \GuzzleHttp\Promise\Promise createSessionAsync(array $args = [])
  48.  * @method \Aws\Result deleteBucket(array $args = [])
  49.  * @method \GuzzleHttp\Promise\Promise deleteBucketAsync(array $args = [])
  50.  * @method \Aws\Result deleteBucketAnalyticsConfiguration(array $args = [])
  51.  * @method \GuzzleHttp\Promise\Promise deleteBucketAnalyticsConfigurationAsync(array $args = [])
  52.  * @method \Aws\Result deleteBucketCors(array $args = [])
  53.  * @method \GuzzleHttp\Promise\Promise deleteBucketCorsAsync(array $args = [])
  54.  * @method \Aws\Result deleteBucketEncryption(array $args = [])
  55.  * @method \GuzzleHttp\Promise\Promise deleteBucketEncryptionAsync(array $args = [])
  56.  * @method \Aws\Result deleteBucketIntelligentTieringConfiguration(array $args = [])
  57.  * @method \GuzzleHttp\Promise\Promise deleteBucketIntelligentTieringConfigurationAsync(array $args = [])
  58.  * @method \Aws\Result deleteBucketInventoryConfiguration(array $args = [])
  59.  * @method \GuzzleHttp\Promise\Promise deleteBucketInventoryConfigurationAsync(array $args = [])
  60.  * @method \Aws\Result deleteBucketLifecycle(array $args = [])
  61.  * @method \GuzzleHttp\Promise\Promise deleteBucketLifecycleAsync(array $args = [])
  62.  * @method \Aws\Result deleteBucketMetricsConfiguration(array $args = [])
  63.  * @method \GuzzleHttp\Promise\Promise deleteBucketMetricsConfigurationAsync(array $args = [])
  64.  * @method \Aws\Result deleteBucketOwnershipControls(array $args = [])
  65.  * @method \GuzzleHttp\Promise\Promise deleteBucketOwnershipControlsAsync(array $args = [])
  66.  * @method \Aws\Result deleteBucketPolicy(array $args = [])
  67.  * @method \GuzzleHttp\Promise\Promise deleteBucketPolicyAsync(array $args = [])
  68.  * @method \Aws\Result deleteBucketReplication(array $args = [])
  69.  * @method \GuzzleHttp\Promise\Promise deleteBucketReplicationAsync(array $args = [])
  70.  * @method \Aws\Result deleteBucketTagging(array $args = [])
  71.  * @method \GuzzleHttp\Promise\Promise deleteBucketTaggingAsync(array $args = [])
  72.  * @method \Aws\Result deleteBucketWebsite(array $args = [])
  73.  * @method \GuzzleHttp\Promise\Promise deleteBucketWebsiteAsync(array $args = [])
  74.  * @method \Aws\Result deleteObject(array $args = [])
  75.  * @method \GuzzleHttp\Promise\Promise deleteObjectAsync(array $args = [])
  76.  * @method \Aws\Result deleteObjectTagging(array $args = [])
  77.  * @method \GuzzleHttp\Promise\Promise deleteObjectTaggingAsync(array $args = [])
  78.  * @method \Aws\Result deleteObjects(array $args = [])
  79.  * @method \GuzzleHttp\Promise\Promise deleteObjectsAsync(array $args = [])
  80.  * @method \Aws\Result deletePublicAccessBlock(array $args = [])
  81.  * @method \GuzzleHttp\Promise\Promise deletePublicAccessBlockAsync(array $args = [])
  82.  * @method \Aws\Result getBucketAccelerateConfiguration(array $args = [])
  83.  * @method \GuzzleHttp\Promise\Promise getBucketAccelerateConfigurationAsync(array $args = [])
  84.  * @method \Aws\Result getBucketAcl(array $args = [])
  85.  * @method \GuzzleHttp\Promise\Promise getBucketAclAsync(array $args = [])
  86.  * @method \Aws\Result getBucketAnalyticsConfiguration(array $args = [])
  87.  * @method \GuzzleHttp\Promise\Promise getBucketAnalyticsConfigurationAsync(array $args = [])
  88.  * @method \Aws\Result getBucketCors(array $args = [])
  89.  * @method \GuzzleHttp\Promise\Promise getBucketCorsAsync(array $args = [])
  90.  * @method \Aws\Result getBucketEncryption(array $args = [])
  91.  * @method \GuzzleHttp\Promise\Promise getBucketEncryptionAsync(array $args = [])
  92.  * @method \Aws\Result getBucketIntelligentTieringConfiguration(array $args = [])
  93.  * @method \GuzzleHttp\Promise\Promise getBucketIntelligentTieringConfigurationAsync(array $args = [])
  94.  * @method \Aws\Result getBucketInventoryConfiguration(array $args = [])
  95.  * @method \GuzzleHttp\Promise\Promise getBucketInventoryConfigurationAsync(array $args = [])
  96.  * @method \Aws\Result getBucketLifecycle(array $args = [])
  97.  * @method \GuzzleHttp\Promise\Promise getBucketLifecycleAsync(array $args = [])
  98.  * @method \Aws\Result getBucketLifecycleConfiguration(array $args = [])
  99.  * @method \GuzzleHttp\Promise\Promise getBucketLifecycleConfigurationAsync(array $args = [])
  100.  * @method \Aws\Result getBucketLocation(array $args = [])
  101.  * @method \GuzzleHttp\Promise\Promise getBucketLocationAsync(array $args = [])
  102.  * @method \Aws\Result getBucketLogging(array $args = [])
  103.  * @method \GuzzleHttp\Promise\Promise getBucketLoggingAsync(array $args = [])
  104.  * @method \Aws\Result getBucketMetricsConfiguration(array $args = [])
  105.  * @method \GuzzleHttp\Promise\Promise getBucketMetricsConfigurationAsync(array $args = [])
  106.  * @method \Aws\Result getBucketNotification(array $args = [])
  107.  * @method \GuzzleHttp\Promise\Promise getBucketNotificationAsync(array $args = [])
  108.  * @method \Aws\Result getBucketNotificationConfiguration(array $args = [])
  109.  * @method \GuzzleHttp\Promise\Promise getBucketNotificationConfigurationAsync(array $args = [])
  110.  * @method \Aws\Result getBucketOwnershipControls(array $args = [])
  111.  * @method \GuzzleHttp\Promise\Promise getBucketOwnershipControlsAsync(array $args = [])
  112.  * @method \Aws\Result getBucketPolicy(array $args = [])
  113.  * @method \GuzzleHttp\Promise\Promise getBucketPolicyAsync(array $args = [])
  114.  * @method \Aws\Result getBucketPolicyStatus(array $args = [])
  115.  * @method \GuzzleHttp\Promise\Promise getBucketPolicyStatusAsync(array $args = [])
  116.  * @method \Aws\Result getBucketReplication(array $args = [])
  117.  * @method \GuzzleHttp\Promise\Promise getBucketReplicationAsync(array $args = [])
  118.  * @method \Aws\Result getBucketRequestPayment(array $args = [])
  119.  * @method \GuzzleHttp\Promise\Promise getBucketRequestPaymentAsync(array $args = [])
  120.  * @method \Aws\Result getBucketTagging(array $args = [])
  121.  * @method \GuzzleHttp\Promise\Promise getBucketTaggingAsync(array $args = [])
  122.  * @method \Aws\Result getBucketVersioning(array $args = [])
  123.  * @method \GuzzleHttp\Promise\Promise getBucketVersioningAsync(array $args = [])
  124.  * @method \Aws\Result getBucketWebsite(array $args = [])
  125.  * @method \GuzzleHttp\Promise\Promise getBucketWebsiteAsync(array $args = [])
  126.  * @method \Aws\Result getObject(array $args = [])
  127.  * @method \GuzzleHttp\Promise\Promise getObjectAsync(array $args = [])
  128.  * @method \Aws\Result getObjectAcl(array $args = [])
  129.  * @method \GuzzleHttp\Promise\Promise getObjectAclAsync(array $args = [])
  130.  * @method \Aws\Result getObjectAttributes(array $args = [])
  131.  * @method \GuzzleHttp\Promise\Promise getObjectAttributesAsync(array $args = [])
  132.  * @method \Aws\Result getObjectLegalHold(array $args = [])
  133.  * @method \GuzzleHttp\Promise\Promise getObjectLegalHoldAsync(array $args = [])
  134.  * @method \Aws\Result getObjectLockConfiguration(array $args = [])
  135.  * @method \GuzzleHttp\Promise\Promise getObjectLockConfigurationAsync(array $args = [])
  136.  * @method \Aws\Result getObjectRetention(array $args = [])
  137.  * @method \GuzzleHttp\Promise\Promise getObjectRetentionAsync(array $args = [])
  138.  * @method \Aws\Result getObjectTagging(array $args = [])
  139.  * @method \GuzzleHttp\Promise\Promise getObjectTaggingAsync(array $args = [])
  140.  * @method \Aws\Result getObjectTorrent(array $args = [])
  141.  * @method \GuzzleHttp\Promise\Promise getObjectTorrentAsync(array $args = [])
  142.  * @method \Aws\Result getPublicAccessBlock(array $args = [])
  143.  * @method \GuzzleHttp\Promise\Promise getPublicAccessBlockAsync(array $args = [])
  144.  * @method \Aws\Result headBucket(array $args = [])
  145.  * @method \GuzzleHttp\Promise\Promise headBucketAsync(array $args = [])
  146.  * @method \Aws\Result headObject(array $args = [])
  147.  * @method \GuzzleHttp\Promise\Promise headObjectAsync(array $args = [])
  148.  * @method \Aws\Result listBucketAnalyticsConfigurations(array $args = [])
  149.  * @method \GuzzleHttp\Promise\Promise listBucketAnalyticsConfigurationsAsync(array $args = [])
  150.  * @method \Aws\Result listBucketIntelligentTieringConfigurations(array $args = [])
  151.  * @method \GuzzleHttp\Promise\Promise listBucketIntelligentTieringConfigurationsAsync(array $args = [])
  152.  * @method \Aws\Result listBucketInventoryConfigurations(array $args = [])
  153.  * @method \GuzzleHttp\Promise\Promise listBucketInventoryConfigurationsAsync(array $args = [])
  154.  * @method \Aws\Result listBucketMetricsConfigurations(array $args = [])
  155.  * @method \GuzzleHttp\Promise\Promise listBucketMetricsConfigurationsAsync(array $args = [])
  156.  * @method \Aws\Result listBuckets(array $args = [])
  157.  * @method \GuzzleHttp\Promise\Promise listBucketsAsync(array $args = [])
  158.  * @method \Aws\Result listDirectoryBuckets(array $args = [])
  159.  * @method \GuzzleHttp\Promise\Promise listDirectoryBucketsAsync(array $args = [])
  160.  * @method \Aws\Result listMultipartUploads(array $args = [])
  161.  * @method \GuzzleHttp\Promise\Promise listMultipartUploadsAsync(array $args = [])
  162.  * @method \Aws\Result listObjectVersions(array $args = [])
  163.  * @method \GuzzleHttp\Promise\Promise listObjectVersionsAsync(array $args = [])
  164.  * @method \Aws\Result listObjects(array $args = [])
  165.  * @method \GuzzleHttp\Promise\Promise listObjectsAsync(array $args = [])
  166.  * @method \Aws\Result listObjectsV2(array $args = [])
  167.  * @method \GuzzleHttp\Promise\Promise listObjectsV2Async(array $args = [])
  168.  * @method \Aws\Result listParts(array $args = [])
  169.  * @method \GuzzleHttp\Promise\Promise listPartsAsync(array $args = [])
  170.  * @method \Aws\Result putBucketAccelerateConfiguration(array $args = [])
  171.  * @method \GuzzleHttp\Promise\Promise putBucketAccelerateConfigurationAsync(array $args = [])
  172.  * @method \Aws\Result putBucketAcl(array $args = [])
  173.  * @method \GuzzleHttp\Promise\Promise putBucketAclAsync(array $args = [])
  174.  * @method \Aws\Result putBucketAnalyticsConfiguration(array $args = [])
  175.  * @method \GuzzleHttp\Promise\Promise putBucketAnalyticsConfigurationAsync(array $args = [])
  176.  * @method \Aws\Result putBucketCors(array $args = [])
  177.  * @method \GuzzleHttp\Promise\Promise putBucketCorsAsync(array $args = [])
  178.  * @method \Aws\Result putBucketEncryption(array $args = [])
  179.  * @method \GuzzleHttp\Promise\Promise putBucketEncryptionAsync(array $args = [])
  180.  * @method \Aws\Result putBucketIntelligentTieringConfiguration(array $args = [])
  181.  * @method \GuzzleHttp\Promise\Promise putBucketIntelligentTieringConfigurationAsync(array $args = [])
  182.  * @method \Aws\Result putBucketInventoryConfiguration(array $args = [])
  183.  * @method \GuzzleHttp\Promise\Promise putBucketInventoryConfigurationAsync(array $args = [])
  184.  * @method \Aws\Result putBucketLifecycle(array $args = [])
  185.  * @method \GuzzleHttp\Promise\Promise putBucketLifecycleAsync(array $args = [])
  186.  * @method \Aws\Result putBucketLifecycleConfiguration(array $args = [])
  187.  * @method \GuzzleHttp\Promise\Promise putBucketLifecycleConfigurationAsync(array $args = [])
  188.  * @method \Aws\Result putBucketLogging(array $args = [])
  189.  * @method \GuzzleHttp\Promise\Promise putBucketLoggingAsync(array $args = [])
  190.  * @method \Aws\Result putBucketMetricsConfiguration(array $args = [])
  191.  * @method \GuzzleHttp\Promise\Promise putBucketMetricsConfigurationAsync(array $args = [])
  192.  * @method \Aws\Result putBucketNotification(array $args = [])
  193.  * @method \GuzzleHttp\Promise\Promise putBucketNotificationAsync(array $args = [])
  194.  * @method \Aws\Result putBucketNotificationConfiguration(array $args = [])
  195.  * @method \GuzzleHttp\Promise\Promise putBucketNotificationConfigurationAsync(array $args = [])
  196.  * @method \Aws\Result putBucketOwnershipControls(array $args = [])
  197.  * @method \GuzzleHttp\Promise\Promise putBucketOwnershipControlsAsync(array $args = [])
  198.  * @method \Aws\Result putBucketPolicy(array $args = [])
  199.  * @method \GuzzleHttp\Promise\Promise putBucketPolicyAsync(array $args = [])
  200.  * @method \Aws\Result putBucketReplication(array $args = [])
  201.  * @method \GuzzleHttp\Promise\Promise putBucketReplicationAsync(array $args = [])
  202.  * @method \Aws\Result putBucketRequestPayment(array $args = [])
  203.  * @method \GuzzleHttp\Promise\Promise putBucketRequestPaymentAsync(array $args = [])
  204.  * @method \Aws\Result putBucketTagging(array $args = [])
  205.  * @method \GuzzleHttp\Promise\Promise putBucketTaggingAsync(array $args = [])
  206.  * @method \Aws\Result putBucketVersioning(array $args = [])
  207.  * @method \GuzzleHttp\Promise\Promise putBucketVersioningAsync(array $args = [])
  208.  * @method \Aws\Result putBucketWebsite(array $args = [])
  209.  * @method \GuzzleHttp\Promise\Promise putBucketWebsiteAsync(array $args = [])
  210.  * @method \Aws\Result putObject(array $args = [])
  211.  * @method \GuzzleHttp\Promise\Promise putObjectAsync(array $args = [])
  212.  * @method \Aws\Result putObjectAcl(array $args = [])
  213.  * @method \GuzzleHttp\Promise\Promise putObjectAclAsync(array $args = [])
  214.  * @method \Aws\Result putObjectLegalHold(array $args = [])
  215.  * @method \GuzzleHttp\Promise\Promise putObjectLegalHoldAsync(array $args = [])
  216.  * @method \Aws\Result putObjectLockConfiguration(array $args = [])
  217.  * @method \GuzzleHttp\Promise\Promise putObjectLockConfigurationAsync(array $args = [])
  218.  * @method \Aws\Result putObjectRetention(array $args = [])
  219.  * @method \GuzzleHttp\Promise\Promise putObjectRetentionAsync(array $args = [])
  220.  * @method \Aws\Result putObjectTagging(array $args = [])
  221.  * @method \GuzzleHttp\Promise\Promise putObjectTaggingAsync(array $args = [])
  222.  * @method \Aws\Result putPublicAccessBlock(array $args = [])
  223.  * @method \GuzzleHttp\Promise\Promise putPublicAccessBlockAsync(array $args = [])
  224.  * @method \Aws\Result restoreObject(array $args = [])
  225.  * @method \GuzzleHttp\Promise\Promise restoreObjectAsync(array $args = [])
  226.  * @method \Aws\Result selectObjectContent(array $args = [])
  227.  * @method \GuzzleHttp\Promise\Promise selectObjectContentAsync(array $args = [])
  228.  * @method \Aws\Result uploadPart(array $args = [])
  229.  * @method \GuzzleHttp\Promise\Promise uploadPartAsync(array $args = [])
  230.  * @method \Aws\Result uploadPartCopy(array $args = [])
  231.  * @method \GuzzleHttp\Promise\Promise uploadPartCopyAsync(array $args = [])
  232.  * @method \Aws\Result writeGetObjectResponse(array $args = [])
  233.  * @method \GuzzleHttp\Promise\Promise writeGetObjectResponseAsync(array $args = [])
  234.  */
  235. class S3Client extends AwsClient implements S3ClientInterface
  236. {
  237.     use S3ClientTrait;
  239.     /** @var array */
  240.     private static $mandatoryAttributes = ['Bucket', 'Key'];
  242.     public static function getArguments()
  243.     {
  244.         $args = parent::getArguments();
  245.         $args['retries']['fn'] = [__CLASS__, '_applyRetryConfig'];
  246.         $args['api_provider']['fn'] = [__CLASS__, '_applyApiProvider'];
  248.         return $args + [
  249.             'bucket_endpoint' => [
  250.                 'type'    => 'config',
  251.                 'valid'   => ['bool'],
  252.                 'doc'     => 'Set to true to send requests to a hardcoded '
  253.                     . 'bucket endpoint rather than create an endpoint as a '
  254.                     . 'result of injecting the bucket into the URL. This '
  255.                     . 'option is useful for interacting with CNAME endpoints.',
  256.             ],
  257.             'use_arn_region' => [
  258.                 'type'    => 'config',
  259.                 'valid'   => [
  260.                     'bool',
  261.                     Configuration::class,
  262.                     CacheInterface::class,
  263.                     'callable'
  264.                 ],
  265.                 'doc'     => 'Set to true to allow passed in ARNs to override'
  266.                     . ' client region. Accepts...',
  267.                 'fn' => [__CLASS__, '_apply_use_arn_region'],
  268.                 'default' => [UseArnRegionConfigurationProvider::class, 'defaultProvider'],
  269.             ],
  270.             'use_accelerate_endpoint' => [
  271.                 'type' => 'config',
  272.                 'valid' => ['bool'],
  273.                 'doc' => 'Set to true to send requests to an S3 Accelerate'
  274.                     . ' endpoint by default. Can be enabled or disabled on'
  275.                     . ' individual operations by setting'
  276.                     . ' \'@use_accelerate_endpoint\' to true or false. Note:'
  277.                     . ' you must enable S3 Accelerate on a bucket before it can'
  278.                     . ' be accessed via an Accelerate endpoint.',
  279.                 'default' => false,
  280.             ],
  281.             'use_path_style_endpoint' => [
  282.                 'type' => 'config',
  283.                 'valid' => ['bool'],
  284.                 'doc' => 'Set to true to send requests to an S3 path style'
  285.                     . ' endpoint by default.'
  286.                     . ' Can be enabled or disabled on individual operations by setting'
  287.                     . ' \'@use_path_style_endpoint\' to true or false.',
  288.                 'default' => false,
  289.             ],
  290.             'disable_multiregion_access_points' => [
  291.                 'type' => 'config',
  292.                 'valid' => ['bool'],
  293.                 'doc' => 'Set to true to disable the usage of'
  294.                     . ' multi region access points. These are enabled by default.'
  295.                     . ' Can be enabled or disabled on individual operations by setting'
  296.                     . ' \'@disable_multiregion_access_points\' to true or false.',
  297.                 'default' => false,
  298.             ],
  299.             'disable_express_session_auth' => [
  300.                 'type' => 'config',
  301.                 'valid' => ['bool'],
  302.                 'doc' => 'Set to true to disable the usage of'
  303.                     . ' s3 express session authentication. This is enabled by default.',
  304.                 'default' => [__CLASS__, '_default_disable_express_session_auth'],
  305.             ],
  306.             's3_express_identity_provider' => [
  307.                 'type'    => 'config',
  308.                 'valid'   => [
  309.                     'bool',
  310.                     'callable'
  311.                 ],
  312.                 'doc'     => 'Specifies the provider used to generate identities to sign s3 express requests.  '
  313.                     . 'Set to `false` to disable s3 express auth, or a callable provider used to create s3 express '
  314.                     . 'identities or return null.',
  315.                 'default' => [__CLASS__, '_default_s3_express_identity_provider'],
  316.             ],
  317.         ];
  318.     }
  320.     /**
  321.      * {@inheritdoc}
  322.      *
  323.      * In addition to the options available to
  324.      * {@see Aws\AwsClient::__construct}, S3Client accepts the following
  325.      * options:
  326.      *
  327.      * - bucket_endpoint: (bool) Set to true to send requests to a
  328.      *   hardcoded bucket endpoint rather than create an endpoint as a result
  329.      *   of injecting the bucket into the URL. This option is useful for
  330.      *   interacting with CNAME endpoints. Note: if you are using version 2.243.0
  331.      *   and above and do not expect the bucket name to appear in the host, you will
  332.      *   also need to set `use_path_style_endpoint` to `true`.
  333.      * - calculate_md5: (bool) Set to false to disable calculating an MD5
  334.      *   for all Amazon S3 signed uploads.
  335.      * - s3_us_east_1_regional_endpoint:
  336.      *   (Aws\S3\RegionalEndpoint\ConfigurationInterface|Aws\CacheInterface\|callable|string|array)
  337.      *   Specifies whether to use regional or legacy endpoints for the us-east-1
  338.      *   region. Provide an Aws\S3\RegionalEndpoint\ConfigurationInterface object, an
  339.      *   instance of Aws\CacheInterface, a callable configuration provider used
  340.      *   to create endpoint configuration, a string value of `legacy` or
  341.      *   `regional`, or an associative array with the following keys:
  342.      *   endpoint_types: (string)  Set to `legacy` or `regional`, defaults to
  343.      *   `legacy`
  344.      * - use_accelerate_endpoint: (bool) Set to true to send requests to an S3
  345.      *   Accelerate endpoint by default. Can be enabled or disabled on
  346.      *   individual operations by setting '@use_accelerate_endpoint' to true or
  347.      *   false. Note: you must enable S3 Accelerate on a bucket before it can be
  348.      *   accessed via an Accelerate endpoint.
  349.      * - use_arn_region: (Aws\S3\UseArnRegion\ConfigurationInterface,
  350.      *   Aws\CacheInterface, bool, callable) Set to true to enable the client
  351.      *   to use the region from a supplied ARN argument instead of the client's
  352.      *   region. Provide an instance of Aws\S3\UseArnRegion\ConfigurationInterface,
  353.      *   an instance of Aws\CacheInterface, a callable that provides a promise for
  354.      *   a Configuration object, or a boolean value. Defaults to false (i.e.
  355.      *   the SDK will not follow the ARN region if it conflicts with the client
  356.      *   region and instead throw an error).
  357.      * - use_dual_stack_endpoint: (bool) Set to true to send requests to an S3
  358.      *   Dual Stack endpoint by default, which enables IPv6 Protocol.
  359.      *   Can be enabled or disabled on individual operations by setting
  360.      *   '@use_dual_stack_endpoint\' to true or false. Note:
  361.      *   you cannot use it together with an accelerate endpoint.
  362.      * - use_path_style_endpoint: (bool) Set to true to send requests to an S3
  363.      *   path style endpoint by default.
  364.      *   Can be enabled or disabled on individual operations by setting
  365.      *   '@use_path_style_endpoint\' to true or false. Note:
  366.      *   you cannot use it together with an accelerate endpoint.
  367.      * - disable_multiregion_access_points: (bool) Set to true to disable
  368.      *   sending multi region requests.  They are enabled by default.
  369.      *   Can be enabled or disabled on individual operations by setting
  370.      *   '@disable_multiregion_access_points\' to true or false. Note:
  371.      *   you cannot use it together with an accelerate or dualstack endpoint.
  372.      *
  373.      * @param array $args
  374.      */
  375.     public function __construct(array $args)
  376.     {
  377.         if (
  378.             !isset($args['s3_us_east_1_regional_endpoint'])
  379.             || $args['s3_us_east_1_regional_endpoint'] instanceof CacheInterface
  380.         ) {
  381.             $args['s3_us_east_1_regional_endpoint'] = ConfigurationProvider::defaultProvider($args);
  382.         }
  383.         $this->addBuiltIns($args);
  384.         parent::__construct($args);
  385.         $stack = $this->getHandlerList();
  386.         $stack->appendInit(SSECMiddleware::wrap($this->getEndpoint()->getScheme()), 's3.ssec');
  387.         $stack->appendBuild(ApplyChecksumMiddleware::wrap($this->getApi()), 's3.checksum');
  388.         $stack->appendBuild(
  389.             Middleware::contentType(['PutObject', 'UploadPart']),
  390.             's3.content_type'
  391.         );
  393.         if ($this->getConfig('bucket_endpoint')) {
  394.             $stack->appendBuild(BucketEndpointMiddleware::wrap(), 's3.bucket_endpoint');
  395.         } elseif (!$this->isUseEndpointV2()) {
  396.             $stack->appendBuild(
  397.                 S3EndpointMiddleware::wrap(
  398.                     $this->getRegion(),
  399.                     $this->getConfig('endpoint_provider'),
  400.                     [
  401.                         'accelerate' => $this->getConfig('use_accelerate_endpoint'),
  402.                         'path_style' => $this->getConfig('use_path_style_endpoint'),
  403.                         'use_fips_endpoint' => $this->getConfig('use_fips_endpoint'),
  404.                         'dual_stack' =>
  405.                             $this->getConfig('use_dual_stack_endpoint')->isUseDualStackEndpoint(),
  407.                     ]
  408.                 ),
  409.                 's3.endpoint_middleware'
  410.             );
  411.         }
  413.         $stack->appendBuild(
  414.             BucketEndpointArnMiddleware::wrap(
  415.                 $this->getApi(),
  416.                 $this->getRegion(),
  417.                 [
  418.                     'use_arn_region' => $this->getConfig('use_arn_region'),
  419.                     'accelerate' => $this->getConfig('use_accelerate_endpoint'),
  420.                     'path_style' => $this->getConfig('use_path_style_endpoint'),
  421.                     'dual_stack' =>
  422.                         $this->getConfig('use_dual_stack_endpoint')->isUseDualStackEndpoint(),
  423.                     'use_fips_endpoint' => $this->getConfig('use_fips_endpoint'),
  424.                     'disable_multiregion_access_points' =>
  425.                         $this->getConfig('disable_multiregion_access_points'),
  426.                     'endpoint' => $args['endpoint'] ?? null
  427.                 ],
  428.                 $this->isUseEndpointV2()
  429.             ),
  430.             's3.bucket_endpoint_arn'
  431.         );
  432.         if ($this->getConfig('disable_express_session_auth')) {
  433.             $stack->prependSign(
  434.                 $this->getDisableExpressSessionAuthMiddleware(),
  435.                 's3.disable_express_session_auth'
  436.             );
  437.         }
  439.         $stack->appendValidate(
  440.             InputValidationMiddleware::wrap($this->getApi(), self::$mandatoryAttributes),
  441.             'input_validation_middleware'
  442.         );
  443.         $stack->appendSign(ExpiresParsingMiddleware::wrap(), 's3.expires_parsing');
  444.         $stack->appendSign(PutObjectUrlMiddleware::wrap(), 's3.put_object_url');
  445.         $stack->appendSign(PermanentRedirectMiddleware::wrap(), 's3.permanent_redirect');
  446.         $stack->appendInit(Middleware::sourceFile($this->getApi()), 's3.source_file');
  447.         $stack->appendInit($this->getSaveAsParameter(), 's3.save_as');
  448.         $stack->appendInit($this->getLocationConstraintMiddleware(), 's3.location');
  449.         $stack->appendInit($this->getEncodingTypeMiddleware(), 's3.auto_encode');
  450.         $stack->appendInit($this->getHeadObjectMiddleware(), 's3.head_object');
  451.         $this->processModel($this->isUseEndpointV2());
  452.         if ($this->isUseEndpointV2()) {
  453.             $stack->after('builder',
  454.                 's3.check_empty_path_with_query',
  455.                 $this->getEmptyPathWithQuery());
  456.         }
  457.     }
  459.     /**
  460.      * Determine if a string is a valid name for a DNS compatible Amazon S3
  461.      * bucket.
  462.      *
  463.      * DNS compatible bucket names can be used as a subdomain in a URL (e.g.,
  464.      * "<bucket>.s3.amazonaws.com").
  465.      *
  466.      * @param string $bucket Bucket name to check.
  467.      *
  468.      * @return bool
  469.      */
  470.     public static function isBucketDnsCompatible($bucket)
  471.     {
  472.         if (!is_string($bucket)) {
  473.             return false;
  474.         }
  475.         $bucketLen = strlen($bucket);
  477.         return ($bucketLen >= 3 && $bucketLen <= 63) &&
  478.             // Cannot look like an IP address
  479.             !filter_var($bucket, FILTER_VALIDATE_IP) &&
  480.             preg_match('/^[a-z0-9]([a-z0-9\-\.]*[a-z0-9])?$/', $bucket);
  481.     }
  483.     public static function _apply_use_arn_region($value, array &$args, HandlerList $list)
  484.     {
  485.         if ($value instanceof CacheInterface) {
  486.             $value = UseArnRegionConfigurationProvider::defaultProvider($args);
  487.         }
  488.         if (is_callable($value)) {
  489.             $value = $value();
  490.         }
  491.         if ($value instanceof PromiseInterface) {
  492.             $value = $value->wait();
  493.         }
  494.         if ($value instanceof ConfigurationInterface) {
  495.             $args['use_arn_region'] = $value;
  496.         } else {
  497.             // The Configuration class itself will validate other inputs
  498.             $args['use_arn_region'] = new Configuration($value);
  499.         }
  500.     }
  502.     public function createPresignedRequest(CommandInterface $command, $expires, array $options = [])
  503.     {
  504.         $command = clone $command;
  505.         $command->getHandlerList()->remove('signer');
  506.         $request = \Aws\serialize($command);
  507.         $signing_name = $command['@context']['signing_service']
  508.             ?? $this->getSigningName($request->getUri()->getHost());
  509.         $signature_version = $this->getSignatureVersionFromCommand($command);
  511.         /** @var \Aws\Signature\SignatureInterface $signer */
  512.         $signer = call_user_func(
  513.             $this->getSignatureProvider(),
  514.             $signature_version,
  515.             $signing_name,
  516.             $this->getConfig('signing_region')
  517.         );
  518.         if ($signature_version == 'v4-s3express') {
  519.             $provider = $this->getConfig('s3_express_identity_provider');
  520.             $credentials = $provider($command)->wait();
  521.         } else {
  522.             $credentials = $this->getCredentials()->wait();
  523.         }
  524.         return $signer->presign(
  525.             $request,
  526.             $credentials,
  527.             $expires,
  528.             $options
  529.         );
  530.     }
  532.     /**
  533.      * Returns the URL to an object identified by its bucket and key.
  534.      *
  535.      * The URL returned by this method is not signed nor does it ensure that the
  536.      * bucket and key given to the method exist. If you need a signed URL, then
  537.      * use the {@see \Aws\S3\S3Client::createPresignedRequest} method and get
  538.      * the URI of the signed request.
  539.      *
  540.      * @param string $bucket  The name of the bucket where the object is located
  541.      * @param string $key     The key of the object
  542.      *
  543.      * @return string The URL to the object
  544.      */
  545.     public function getObjectUrl($bucket, $key)
  546.     {
  547.         $command = $this->getCommand('GetObject', [
  548.             'Bucket' => $bucket,
  549.             'Key'    => $key
  550.         ]);
  552.         return (string) \Aws\serialize($command)->getUri();
  553.     }
  555.     /**
  556.      * Raw URL encode a key and allow for '/' characters
  557.      *
  558.      * @param string $key Key to encode
  559.      *
  560.      * @return string Returns the encoded key
  561.      */
  562.     public static function encodeKey($key)
  563.     {
  564.         return str_replace('%2F', '/', rawurlencode($key));
  565.     }
  567.     /**
  568.      * Provides a middleware that removes the need to specify LocationConstraint on CreateBucket.
  569.      *
  570.      * @return \Closure
  571.      */
  572.     private function getLocationConstraintMiddleware()
  573.     {
  574.         $region = $this->getRegion();
  575.         return static function (callable $handler) use ($region) {
  576.             return function (Command $command, $request = null) use ($handler, $region) {
  577.                 if ($command->getName() === 'CreateBucket') {
  578.                     $locationConstraint = $command['CreateBucketConfiguration']['LocationConstraint']
  579.                         ?? null;
  581.                     if ($locationConstraint === 'us-east-1') {
  582.                         unset($command['CreateBucketConfiguration']);
  583.                     } elseif ('us-east-1' !== $region && empty($locationConstraint)) {
  584.                         $command['CreateBucketConfiguration'] = ['LocationConstraint' => $region];
  585.                     }
  586.                 }
  588.                 return $handler($command, $request);
  589.             };
  590.         };
  591.     }
  593.     /**
  594.      * Provides a middleware that supports the `SaveAs` parameter.
  595.      *
  596.      * @return \Closure
  597.      */
  598.     private function getSaveAsParameter()
  599.     {
  600.         return static function (callable $handler) {
  601.             return function (Command $command, $request = null) use ($handler) {
  602.                 if ($command->getName() === 'GetObject' && isset($command['SaveAs'])) {
  603.                     $command['@http']['sink'] = $command['SaveAs'];
  604.                     unset($command['SaveAs']);
  605.                 }
  607.                 return $handler($command, $request);
  608.             };
  609.         };
  610.     }
  612.     /**
  613.      * Provides a middleware that disables content decoding on HeadObject
  614.      * commands.
  615.      *
  616.      * @return \Closure
  617.      */
  618.     private function getHeadObjectMiddleware()
  619.     {
  620.         return static function (callable $handler) {
  621.             return function (
  622.                 CommandInterface $command,
  623.                 RequestInterface $request = null
  624.             ) use ($handler) {
  625.                 if ($command->getName() === 'HeadObject'
  626.                     && !isset($command['@http']['decode_content'])
  627.                 ) {
  628.                     $command['@http']['decode_content'] = false;
  629.                 }
  631.                 return $handler($command, $request);
  632.             };
  633.         };
  634.     }
  636.     /**
  637.      * Provides a middleware that autopopulates the EncodingType parameter on
  638.      * ListObjects commands.
  639.      *
  640.      * @return \Closure
  641.      */
  642.     private function getEncodingTypeMiddleware()
  643.     {
  644.         return static function (callable $handler) {
  645.             return function (Command $command, $request = null) use ($handler) {
  646.                 $autoSet = false;
  647.                 if ($command->getName() === 'ListObjects'
  648.                     && empty($command['EncodingType'])
  649.                 ) {
  650.                     $command['EncodingType'] = 'url';
  651.                     $autoSet = true;
  652.                 }
  654.                 return $handler($command, $request)
  655.                     ->then(function (ResultInterface $result) use ($autoSet) {
  656.                         if ($result['EncodingType'] === 'url' && $autoSet) {
  657.                             static $topLevel = [
  658.                                 'Delimiter',
  659.                                 'Marker',
  660.                                 'NextMarker',
  661.                                 'Prefix',
  662.                             ];
  663.                             static $nested = [
  664.                                 ['Contents', 'Key'],
  665.                                 ['CommonPrefixes', 'Prefix'],
  666.                             ];
  668.                             foreach ($topLevel as $key) {
  669.                                 if (isset($result[$key])) {
  670.                                     $result[$key] = urldecode($result[$key]);
  671.                                 }
  672.                             }
  673.                             foreach ($nested as $steps) {
  674.                                 if (isset($result[$steps[0]])) {
  675.                                     foreach ($result[$steps[0]] as $key => $part) {
  676.                                         if (isset($part[$steps[1]])) {
  677.                                             $result[$steps[0]][$key][$steps[1]]
  678.                                                 = urldecode($part[$steps[1]]);
  679.                                         }
  680.                                     }
  681.                                 }
  682.                             }
  684.                         }
  686.                         return $result;
  687.                     });
  688.             };
  689.         };
  690.     }
  692.     /**
  693.      * Provides a middleware that checks for an empty path and a
  694.      * non-empty query string.
  695.      *
  696.      * @return \Closure
  697.      */
  698.     private function getEmptyPathWithQuery()
  699.     {
  700.         return static function (callable $handler) {
  701.             return function (Command $command, RequestInterface $request) use ($handler) {
  702.                 $uri = $request->getUri();
  703.                 if (empty($uri->getPath()) && !empty($uri->getQuery())) {
  704.                     $uri = $uri->withPath('/');
  705.                     $request = $request->withUri($uri);
  706.                 }
  708.                 return $handler($command, $request);
  709.             };
  710.         };
  711.     }
  713.     /**
  714.      * Provides a middleware that disables express session auth when
  715.      * customers opt out of it.
  716.      *
  717.      * @return \Closure
  718.      */
  719.     private function getDisableExpressSessionAuthMiddleware()
  720.     {
  721.         return function (callable $handler) {
  722.             return function (
  723.                 CommandInterface $command,
  724.                 RequestInterface $request = null
  725.             ) use ($handler) {
  726.                 if (!empty($command['@context']['signature_version'])
  727.                     && $command['@context']['signature_version'] === 'v4-s3express'
  728.                 ) {
  729.                     $command['@context']['signature_version'] = 's3v4';
  730.                 }
  731.                 return $handler($command, $request);
  732.             };
  733.         };
  734.     }
  736.     /**
  737.      * Special handling for when the service name is s3-object-lambda.
  738.      * So, if the host contains s3-object-lambda, then the service name
  739.      * returned is s3-object-lambda, otherwise the default signing service is returned.
  740.      * @param string $host The host to validate if is a s3-object-lambda URL.
  741.      * @return string returns the signing service name to be used
  742.      */
  743.     private function getSigningName($host)
  744.     {
  745.         if (strpos( $host, 's3-object-lambda')) {
  746.             return 's3-object-lambda';
  747.         }
  749.         return $this->getConfig('signing_name');
  750.     }
  752.     public static function _default_disable_express_session_auth(array &$args) {
  753.         return ConfigurationResolver::resolve(
  754.             's3_disable_express_session_auth',
  755.             false,
  756.             'bool',
  757.             $args
  758.         );
  759.     }
  761.     public static function _default_s3_express_identity_provider(array $args)
  762.     {
  763.         if ($args['config']['disable_express_session_auth']) {
  764.             return false;
  765.         }
  766.         return new S3ExpressIdentityProvider($args['region']);
  767.     }
  769.     /**
  770.      * If EndpointProviderV2 is used, removes `Bucket` from request URIs.
  771.      * This is now handled by the endpoint ruleset.
  772.      *
  773.      * Additionally adds a synthetic shape `ExpiresString` and modifies
  774.      * `Expires` type to ensure it remains set to `timestamp`.
  775.      *
  776.      * @param array $args
  777.      * @return void
  778.      *
  779.      * @internal
  780.      */
  781.     private function processModel(bool $isUseEndpointV2): void
  782.     {
  783.         $definition = $this->getApi()->getDefinition();
  785.         if ($isUseEndpointV2) {
  786.             foreach($definition['operations'] as &$operation) {
  787.                 if (isset($operation['http']['requestUri'])) {
  788.                     $requestUri = $operation['http']['requestUri'];
  789.                     if ($requestUri === "/{Bucket}") {
  790.                         $requestUri = str_replace('/{Bucket}', '/', $requestUri);
  791.                     } else {
  792.                         $requestUri = str_replace('/{Bucket}', '', $requestUri);
  793.                     }
  794.                     $operation['http']['requestUri'] = $requestUri;
  795.                 }
  796.             }
  797.         }
  799.         foreach ($definition['shapes'] as $key => &$value) {
  800.             $suffix = 'Output';
  801.             if (substr($key, -strlen($suffix)) === $suffix) {
  802.                 if (isset($value['members']['Expires'])) {
  803.                     $value['members']['Expires']['deprecated'] = true;
  804.                     $value['members']['ExpiresString'] = [
  805.                         'shape' => 'ExpiresString',
  806.                         'location' => 'header',
  807.                         'locationName' => 'Expires'
  808.                     ];
  809.                 }
  810.             }
  811.         }
  812.         $definition['shapes']['ExpiresString']['type'] = 'string';
  813.         $definition['shapes']['Expires']['type'] = 'timestamp';
  815.         $this->getApi()->setDefinition($definition);
  816.     }
  818.     /**
  819.      * Adds service-specific client built-in values
  820.      *
  821.      * @return void
  822.      */
  823.     private function addBuiltIns($args)
  824.     {
  825.         if (isset($args['region'])
  826.             && $args['region'] !== 'us-east-1'
  827.         ) {
  828.             return false;
  829.         }
  831.         if (!isset($args['region'])
  832.             && ConfigurationResolver::resolve('region', '', 'string') !== 'us-east-1'
  833.         ) {
  834.             return false;
  835.         }
  837.         $key = 'AWS::S3::UseGlobalEndpoint';
  838.         $result = $args['s3_us_east_1_regional_endpoint'] instanceof \Closure ?
  839.             $args['s3_us_east_1_regional_endpoint']()->wait() : $args['s3_us_east_1_regional_endpoint'];
  841.         if (is_string($result)) {
  842.             if ($result === 'regional') {
  843.                 $value = false;
  844.             } else if ($result === 'legacy') {
  845.                 $value = true;
  846.             } else {
  847.                 return;
  848.             }
  849.         } else {
  850.             if ($result->isFallback()
  851.                 || $result->getEndpointsType() === 'legacy'
  852.             ) {
  853.                 $value = true;
  854.             } else {
  855.                 $value = false;
  856.             }
  857.         }
  858.         $this->clientBuiltIns[$key] = $value;
  859.     }
  861.     /** @internal */
  862.     public static function _applyRetryConfig($value, $args, HandlerList $list)
  863.     {
  864.         if ($value) {
  865.             $config = \Aws\Retry\ConfigurationProvider::unwrap($value);
  867.             if ($config->getMode() === 'legacy') {
  868.                 $maxRetries = $config->getMaxAttempts() - 1;
  869.                 $decider = RetryMiddleware::createDefaultDecider($maxRetries);
  870.                 $decider = function ($retries, $command, $request, $result, $error) use ($decider, $maxRetries) {
  871.                     $maxRetries = $command['@retries'] ?? $maxRetries;
  873.                     if ($decider($retries, $command, $request, $result, $error)) {
  874.                         return true;
  875.                     }
  877.                     if ($error instanceof AwsException
  878.                         && $retries < $maxRetries
  879.                     ) {
  880.                         if ($error->getResponse()
  881.                             && $error->getResponse()->getStatusCode() >= 400
  882.                         ) {
  883.                             return strpos(
  884.                                     $error->getResponse()->getBody(),
  885.                                     'Your socket connection to the server'
  886.                                 ) !== false;
  887.                         }
  889.                         if ($error->getPrevious() instanceof RequestException) {
  890.                             // All commands except CompleteMultipartUpload are
  891.                             // idempotent and may be retried without worry if a
  892.                             // networking error has occurred.
  893.                             return $command->getName() !== 'CompleteMultipartUpload';
  894.                         }
  895.                     }
  897.                     return false;
  898.                 };
  900.                 $delay = [RetryMiddleware::class, 'exponentialDelay'];
  901.                 $list->appendSign(Middleware::retry($decider, $delay), 'retry');
  902.             } else {
  903.                 $defaultDecider = RetryMiddlewareV2::createDefaultDecider(
  904.                     new QuotaManager(),
  905.                     $config->getMaxAttempts()
  906.                 );
  908.                 $list->appendSign(
  909.                     RetryMiddlewareV2::wrap(
  910.                         $config,
  911.                         [
  912.                             'collect_stats' => $args['stats']['retries'],
  913.                             'decider' => function(
  914.                                 $attempts,
  915.                                 CommandInterface $cmd,
  916.                                 $result
  917.                             ) use ($defaultDecider, $config) {
  918.                                 $isRetryable = $defaultDecider($attempts, $cmd, $result);
  919.                                 if (!$isRetryable
  920.                                     && $result instanceof AwsException
  921.                                     && $attempts < $config->getMaxAttempts()
  922.                                 ) {
  923.                                     if (!empty($result->getResponse())
  924.                                         && $result->getResponse()->getStatusCode() >= 400
  925.                                     ) {
  926.                                         return strpos(
  927.                                                 $result->getResponse()->getBody(),
  928.                                                 'Your socket connection to the server'
  929.                                             ) !== false;
  930.                                     }
  932.                                     if ($result->getPrevious() instanceof RequestException
  933.                                         && $cmd->getName() !== 'CompleteMultipartUpload'
  934.                                     ) {
  935.                                         $isRetryable = true;
  936.                                     }
  937.                                 }
  939.                                 return $isRetryable;
  940.                             }
  941.                         ]
  942.                     ),
  943.                     'retry'
  944.                 );
  945.             }
  946.         }
  947.     }
  949.     /** @internal */
  950.     public static function _applyApiProvider($value, array &$args, HandlerList $list)
  951.     {
  952.         ClientResolver::_apply_api_provider($value, $args);
  953.         $s3Parser = new S3Parser(
  954.             $args['parser'],
  955.             $args['error_parser'],
  956.             $args['api'],
  957.             $args['exception_class']
  958.         );
  959.         $s3Parser->addS3ResultMutator(
  960.             'get-bucket-location',
  961.             new GetBucketLocationResultMutator()
  962.         );
  963.         $s3Parser->addS3ResultMutator(
  964.             'validate-response-checksum',
  965.             new ValidateResponseChecksumResultMutator($args['api'])
  966.         );
  967.         $args['parser'] = $s3Parser;
  968.     }
  970.     /**
  971.      * @internal
  972.      * @codeCoverageIgnore
  973.      */
  974.     public static function applyDocFilters(array $api, array $docs)
  975.     {
  976.         $b64 = '<div class="alert alert-info">This value will be base64 encoded on your behalf.</div>';
  977.         $opt = '<div class="alert alert-info">This value will be computed for you it is not supplied.</div>';
  979.         // Add a note on the CopyObject docs
  980.          $s3ExceptionRetryMessage = "<p>Additional info on response behavior: if there is"
  981.             . " an internal error in S3 after the request was successfully recieved,"
  982.             . " a 200 response will be returned with an <code>S3Exception</code> embedded"
  983.             . " in it; this will still be caught and retried by"
  984.             . " <code>RetryMiddleware.</code></p>";
  986.         $docs['operations']['CopyObject'] .=  $s3ExceptionRetryMessage;
  987.         $docs['operations']['CompleteMultipartUpload'] .=  $s3ExceptionRetryMessage;
  988.         $docs['operations']['UploadPartCopy'] .=  $s3ExceptionRetryMessage;
  989.         $docs['operations']['UploadPart'] .=  $s3ExceptionRetryMessage;
  991.         // Add note about stream ownership in the putObject call
  992.         $guzzleStreamMessage = "<p>Additional info on behavior of the stream"
  993.             . " parameters: Psr7 takes ownership of streams and will automatically close"
  994.             . " streams when this method is called with a stream as the <code>Body</code>"
  995.             . " parameter.  To prevent this, set the <code>Body</code> using"
  996.             . " <code>GuzzleHttp\Psr7\stream_for</code> method with a is an instance of"
  997.             . " <code>Psr\Http\Message\StreamInterface</code>, and it will be returned"
  998.             . " unmodified. This will allow you to keep the stream in scope. </p>";
  999.         $docs['operations']['PutObject'] .=  $guzzleStreamMessage;
  1001.         // Add the SourceFile parameter.
  1002.         $docs['shapes']['SourceFile']['base'] = 'The path to a file on disk to use instead of the Body parameter.';
  1003.         $api['shapes']['SourceFile'] = ['type' => 'string'];
  1004.         $api['shapes']['PutObjectRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
  1005.         $api['shapes']['UploadPartRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
  1007.         // Add the ContentSHA256 parameter.
  1008.         $docs['shapes']['ContentSHA256']['base'] = 'A SHA256 hash of the body content of the request.';
  1009.         $api['shapes']['ContentSHA256'] = ['type' => 'string'];
  1010.         $api['shapes']['PutObjectRequest']['members']['ContentSHA256'] = ['shape' => 'ContentSHA256'];
  1011.         $api['shapes']['UploadPartRequest']['members']['ContentSHA256'] = ['shape' => 'ContentSHA256'];
  1012.         $docs['shapes']['ContentSHA256']['append'] = $opt;
  1014.         // Add the AddContentMD5 parameter.
  1015.         $docs['shapes']['AddContentMD5']['base'] = 'Set to true to calculate the ContentMD5 for the upload.';
  1016.         $api['shapes']['AddContentMD5'] = ['type' => 'boolean'];
  1017.         $api['shapes']['PutObjectRequest']['members']['AddContentMD5'] = ['shape' => 'AddContentMD5'];
  1018.         $api['shapes']['UploadPartRequest']['members']['AddContentMD5'] = ['shape' => 'AddContentMD5'];
  1020.         // Add the SaveAs parameter.
  1021.         $docs['shapes']['SaveAs']['base'] = 'The path to a file on disk to save the object data.';
  1022.         $api['shapes']['SaveAs'] = ['type' => 'string'];
  1023.         $api['shapes']['GetObjectRequest']['members']['SaveAs'] = ['shape' => 'SaveAs'];
  1025.         // Several SSECustomerKey documentation updates.
  1026.         $docs['shapes']['SSECustomerKey']['append'] = $b64;
  1027.         $docs['shapes']['CopySourceSSECustomerKey']['append'] = $b64;
  1028.         $docs['shapes']['SSECustomerKeyMd5']['append'] = $opt;
  1030.         // Add the ObjectURL to various output shapes and documentation.
  1031.         $docs['shapes']['ObjectURL']['base'] = 'The URI of the created object.';
  1032.         $api['shapes']['ObjectURL'] = ['type' => 'string'];
  1033.         $api['shapes']['PutObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
  1034.         $api['shapes']['CopyObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
  1035.         $api['shapes']['CompleteMultipartUploadOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
  1037.         // Fix references to Location Constraint.
  1038.         unset($api['shapes']['CreateBucketRequest']['payload']);
  1039.         $api['shapes']['BucketLocationConstraint']['enum'] = [
  1040.             "ap-northeast-1",
  1041.             "ap-southeast-2",
  1042.             "ap-southeast-1",
  1043.             "cn-north-1",
  1044.             "eu-central-1",
  1045.             "eu-west-1",
  1046.             "us-east-1",
  1047.             "us-west-1",
  1048.             "us-west-2",
  1049.             "sa-east-1",
  1050.         ];
  1052.         // Add a note that the ContentMD5 is automatically computed, except for with PutObject and UploadPart
  1053.         $docs['shapes']['ContentMD5']['append'] = '<div class="alert alert-info">The value will be computed on '
  1054.             . 'your behalf.</div>';
  1055.         $docs['shapes']['ContentMD5']['excludeAppend'] = ['PutObjectRequest', 'UploadPartRequest'];
  1057.         //Add a note to ContentMD5 for PutObject and UploadPart that specifies the value is required
  1058.         // When uploading to a bucket with object lock enabled and that it is not computed automatically
  1059.         $objectLock = '<div class="alert alert-info">This value is required if uploading to a bucket '
  1060.             . 'which has Object Lock enabled. It will not be calculated for you automatically. If you wish to have '
  1061.             . 'the value calculated for you, use the `AddContentMD5` parameter.</div>';
  1062.         $docs['shapes']['ContentMD5']['appendOnly'] = [
  1063.             'message' => $objectLock,
  1064.             'shapes' => ['PutObjectRequest', 'UploadPartRequest']
  1065.         ];
  1067.         // Add `ExpiresString` shape to output structures which contain `Expires`
  1068.         // Deprecate existing `Expires` shapes in output structures
  1069.         // Add/Update documentation for both `ExpiresString` and `Expires`
  1070.         // Ensure `Expires` type remains timestamp
  1071.         foreach ($api['shapes'] as $key => &$value) {
  1072.             $suffix = 'Output';
  1073.             if (substr($key, -strlen($suffix)) === $suffix) {
  1074.                 if (isset($value['members']['Expires'])) {
  1075.                     $value['members']['Expires']['deprecated'] = true;
  1076.                     $value['members']['ExpiresString'] = [
  1077.                         'shape' => 'ExpiresString',
  1078.                         'location' => 'header',
  1079.                         'locationName' => 'Expires'
  1080.                     ];
  1081.                     $docs['shapes']['Expires']['refs'][$key . '$Expires']
  1082.                         .= '<p>This output shape has been deprecated. Please refer to <code>ExpiresString</code> instead.</p>.';
  1083.                 }
  1084.             }
  1085.         }
  1086.         $api['shapes']['ExpiresString']['type'] = 'string';
  1087.         $docs['shapes']['ExpiresString']['base'] = 'The unparsed string value of the <code>Expires</code> output member.';
  1088.         $api['shapes']['Expires']['type'] = 'timestamp';
  1090.         return [
  1091.             new Service($api, ApiProvider::defaultProvider()),
  1092.             new DocModel($docs)
  1093.         ];
  1094.     }
  1096.     /**
  1097.      * @internal
  1098.      * @codeCoverageIgnore
  1099.      */
  1100.     public static function addDocExamples($examples)
  1101.     {
  1102.         $getObjectExample = [
  1103.             'input' => [
  1104.                 'Bucket' => 'arn:aws:s3:us-east-1:123456789012:accesspoint:myaccesspoint',
  1105.                 'Key' => 'my-key'
  1106.             ],
  1107.             'output' => [
  1108.                 'Body' => 'class GuzzleHttp\Psr7\Stream#208 (7) {...}',
  1109.                 'ContentLength' => '11',
  1110.                 'ContentType' => 'application/octet-stream',
  1111.             ],
  1112.             'comments' => [
  1113.                 'input' => '',
  1114.                 'output' => 'Simplified example output'
  1115.             ],
  1116.             'description' => 'The following example retrieves an object by referencing the bucket via an S3 accesss point ARN. Result output is simplified for the example.',
  1117.             'id' => '',
  1118.             'title' => 'To get an object via an S3 access point ARN'
  1119.         ];
  1120.         if (isset($examples['GetObject'])) {
  1121.             $examples['GetObject'] []= $getObjectExample;
  1122.         } else {
  1123.             $examples['GetObject'] = [$getObjectExample];
  1124.         }
  1126.         $putObjectExample = [
  1127.             'input' => [
  1128.                 'Bucket' => 'arn:aws:s3:us-east-1:123456789012:accesspoint:myaccesspoint',
  1129.                 'Key' => 'my-key',
  1130.                 'Body' => 'my-body',
  1131.             ],
  1132.             'output' => [
  1133.                 'ObjectURL' => 'https://my-bucket.s3.us-east-1.amazonaws.com/my-key'
  1134.             ],
  1135.             'comments' => [
  1136.                 'input' => '',
  1137.                 'output' => 'Simplified example output'
  1138.             ],
  1139.             'description' => 'The following example uploads an object by referencing the bucket via an S3 accesss point ARN. Result output is simplified for the example.',
  1140.             'id' => '',
  1141.             'title' => 'To upload an object via an S3 access point ARN'
  1142.         ];
  1143.         if (isset($examples['PutObject'])) {
  1144.             $examples['PutObject'] []= $putObjectExample;
  1145.         } else {
  1146.             $examples['PutObject'] = [$putObjectExample];
  1147.         }
  1149.         return $examples;
  1150.     }
  1152.     /**
  1153.      * @param CommandInterface $command
  1154.      * @return array|mixed|null
  1155.      */
  1156.     private function getSignatureVersionFromCommand(CommandInterface $command)
  1157.     {
  1158.         return $command['@context']['signature_version']
  1159.             ?? $this->getConfig('signature_version');
  1160.     }
  1161. }