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

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\Exception\AwsException;
  12. use Aws\HandlerList;
  13. use Aws\InputValidationMiddleware;
  14. use Aws\Middleware;
  15. use Aws\Retry\QuotaManager;
  16. use Aws\RetryMiddleware;
  17. use Aws\ResultInterface;
  18. use Aws\CommandInterface;
  19. use Aws\RetryMiddlewareV2;
  20. use Aws\S3\UseArnRegion\Configuration;
  21. use Aws\S3\UseArnRegion\ConfigurationInterface;
  22. use Aws\S3\UseArnRegion\ConfigurationProvider as UseArnRegionConfigurationProvider;
  23. use Aws\S3\RegionalEndpoint\ConfigurationProvider;
  24. use GuzzleHttp\Exception\RequestException;
  25. use GuzzleHttp\Promise\Promise;
  26. use GuzzleHttp\Promise\PromiseInterface;
  27. use Psr\Http\Message\RequestInterface;
  29. /**
  30.  * Client used to interact with **Amazon Simple Storage Service (Amazon S3)**.
  31.  *
  32.  * @method \Aws\Result abortMultipartUpload(array $args = [])
  33.  * @method \GuzzleHttp\Promise\Promise abortMultipartUploadAsync(array $args = [])
  34.  * @method \Aws\Result completeMultipartUpload(array $args = [])
  35.  * @method \GuzzleHttp\Promise\Promise completeMultipartUploadAsync(array $args = [])
  36.  * @method \Aws\Result copyObject(array $args = [])
  37.  * @method \GuzzleHttp\Promise\Promise copyObjectAsync(array $args = [])
  38.  * @method \Aws\Result createBucket(array $args = [])
  39.  * @method \GuzzleHttp\Promise\Promise createBucketAsync(array $args = [])
  40.  * @method \Aws\Result createMultipartUpload(array $args = [])
  41.  * @method \GuzzleHttp\Promise\Promise createMultipartUploadAsync(array $args = [])
  42.  * @method \Aws\Result deleteBucket(array $args = [])
  43.  * @method \GuzzleHttp\Promise\Promise deleteBucketAsync(array $args = [])
  44.  * @method \Aws\Result deleteBucketAnalyticsConfiguration(array $args = [])
  45.  * @method \GuzzleHttp\Promise\Promise deleteBucketAnalyticsConfigurationAsync(array $args = [])
  46.  * @method \Aws\Result deleteBucketCors(array $args = [])
  47.  * @method \GuzzleHttp\Promise\Promise deleteBucketCorsAsync(array $args = [])
  48.  * @method \Aws\Result deleteBucketEncryption(array $args = [])
  49.  * @method \GuzzleHttp\Promise\Promise deleteBucketEncryptionAsync(array $args = [])
  50.  * @method \Aws\Result deleteBucketIntelligentTieringConfiguration(array $args = [])
  51.  * @method \GuzzleHttp\Promise\Promise deleteBucketIntelligentTieringConfigurationAsync(array $args = [])
  52.  * @method \Aws\Result deleteBucketInventoryConfiguration(array $args = [])
  53.  * @method \GuzzleHttp\Promise\Promise deleteBucketInventoryConfigurationAsync(array $args = [])
  54.  * @method \Aws\Result deleteBucketLifecycle(array $args = [])
  55.  * @method \GuzzleHttp\Promise\Promise deleteBucketLifecycleAsync(array $args = [])
  56.  * @method \Aws\Result deleteBucketMetricsConfiguration(array $args = [])
  57.  * @method \GuzzleHttp\Promise\Promise deleteBucketMetricsConfigurationAsync(array $args = [])
  58.  * @method \Aws\Result deleteBucketOwnershipControls(array $args = [])
  59.  * @method \GuzzleHttp\Promise\Promise deleteBucketOwnershipControlsAsync(array $args = [])
  60.  * @method \Aws\Result deleteBucketPolicy(array $args = [])
  61.  * @method \GuzzleHttp\Promise\Promise deleteBucketPolicyAsync(array $args = [])
  62.  * @method \Aws\Result deleteBucketReplication(array $args = [])
  63.  * @method \GuzzleHttp\Promise\Promise deleteBucketReplicationAsync(array $args = [])
  64.  * @method \Aws\Result deleteBucketTagging(array $args = [])
  65.  * @method \GuzzleHttp\Promise\Promise deleteBucketTaggingAsync(array $args = [])
  66.  * @method \Aws\Result deleteBucketWebsite(array $args = [])
  67.  * @method \GuzzleHttp\Promise\Promise deleteBucketWebsiteAsync(array $args = [])
  68.  * @method \Aws\Result deleteObject(array $args = [])
  69.  * @method \GuzzleHttp\Promise\Promise deleteObjectAsync(array $args = [])
  70.  * @method \Aws\Result deleteObjectTagging(array $args = [])
  71.  * @method \GuzzleHttp\Promise\Promise deleteObjectTaggingAsync(array $args = [])
  72.  * @method \Aws\Result deleteObjects(array $args = [])
  73.  * @method \GuzzleHttp\Promise\Promise deleteObjectsAsync(array $args = [])
  74.  * @method \Aws\Result deletePublicAccessBlock(array $args = [])
  75.  * @method \GuzzleHttp\Promise\Promise deletePublicAccessBlockAsync(array $args = [])
  76.  * @method \Aws\Result getBucketAccelerateConfiguration(array $args = [])
  77.  * @method \GuzzleHttp\Promise\Promise getBucketAccelerateConfigurationAsync(array $args = [])
  78.  * @method \Aws\Result getBucketAcl(array $args = [])
  79.  * @method \GuzzleHttp\Promise\Promise getBucketAclAsync(array $args = [])
  80.  * @method \Aws\Result getBucketAnalyticsConfiguration(array $args = [])
  81.  * @method \GuzzleHttp\Promise\Promise getBucketAnalyticsConfigurationAsync(array $args = [])
  82.  * @method \Aws\Result getBucketCors(array $args = [])
  83.  * @method \GuzzleHttp\Promise\Promise getBucketCorsAsync(array $args = [])
  84.  * @method \Aws\Result getBucketEncryption(array $args = [])
  85.  * @method \GuzzleHttp\Promise\Promise getBucketEncryptionAsync(array $args = [])
  86.  * @method \Aws\Result getBucketIntelligentTieringConfiguration(array $args = [])
  87.  * @method \GuzzleHttp\Promise\Promise getBucketIntelligentTieringConfigurationAsync(array $args = [])
  88.  * @method \Aws\Result getBucketInventoryConfiguration(array $args = [])
  89.  * @method \GuzzleHttp\Promise\Promise getBucketInventoryConfigurationAsync(array $args = [])
  90.  * @method \Aws\Result getBucketLifecycle(array $args = [])
  91.  * @method \GuzzleHttp\Promise\Promise getBucketLifecycleAsync(array $args = [])
  92.  * @method \Aws\Result getBucketLifecycleConfiguration(array $args = [])
  93.  * @method \GuzzleHttp\Promise\Promise getBucketLifecycleConfigurationAsync(array $args = [])
  94.  * @method \Aws\Result getBucketLocation(array $args = [])
  95.  * @method \GuzzleHttp\Promise\Promise getBucketLocationAsync(array $args = [])
  96.  * @method \Aws\Result getBucketLogging(array $args = [])
  97.  * @method \GuzzleHttp\Promise\Promise getBucketLoggingAsync(array $args = [])
  98.  * @method \Aws\Result getBucketMetricsConfiguration(array $args = [])
  99.  * @method \GuzzleHttp\Promise\Promise getBucketMetricsConfigurationAsync(array $args = [])
  100.  * @method \Aws\Result getBucketNotification(array $args = [])
  101.  * @method \GuzzleHttp\Promise\Promise getBucketNotificationAsync(array $args = [])
  102.  * @method \Aws\Result getBucketNotificationConfiguration(array $args = [])
  103.  * @method \GuzzleHttp\Promise\Promise getBucketNotificationConfigurationAsync(array $args = [])
  104.  * @method \Aws\Result getBucketOwnershipControls(array $args = [])
  105.  * @method \GuzzleHttp\Promise\Promise getBucketOwnershipControlsAsync(array $args = [])
  106.  * @method \Aws\Result getBucketPolicy(array $args = [])
  107.  * @method \GuzzleHttp\Promise\Promise getBucketPolicyAsync(array $args = [])
  108.  * @method \Aws\Result getBucketPolicyStatus(array $args = [])
  109.  * @method \GuzzleHttp\Promise\Promise getBucketPolicyStatusAsync(array $args = [])
  110.  * @method \Aws\Result getBucketReplication(array $args = [])
  111.  * @method \GuzzleHttp\Promise\Promise getBucketReplicationAsync(array $args = [])
  112.  * @method \Aws\Result getBucketRequestPayment(array $args = [])
  113.  * @method \GuzzleHttp\Promise\Promise getBucketRequestPaymentAsync(array $args = [])
  114.  * @method \Aws\Result getBucketTagging(array $args = [])
  115.  * @method \GuzzleHttp\Promise\Promise getBucketTaggingAsync(array $args = [])
  116.  * @method \Aws\Result getBucketVersioning(array $args = [])
  117.  * @method \GuzzleHttp\Promise\Promise getBucketVersioningAsync(array $args = [])
  118.  * @method \Aws\Result getBucketWebsite(array $args = [])
  119.  * @method \GuzzleHttp\Promise\Promise getBucketWebsiteAsync(array $args = [])
  120.  * @method \Aws\Result getObject(array $args = [])
  121.  * @method \GuzzleHttp\Promise\Promise getObjectAsync(array $args = [])
  122.  * @method \Aws\Result getObjectAcl(array $args = [])
  123.  * @method \GuzzleHttp\Promise\Promise getObjectAclAsync(array $args = [])
  124.  * @method \Aws\Result getObjectAttributes(array $args = [])
  125.  * @method \GuzzleHttp\Promise\Promise getObjectAttributesAsync(array $args = [])
  126.  * @method \Aws\Result getObjectLegalHold(array $args = [])
  127.  * @method \GuzzleHttp\Promise\Promise getObjectLegalHoldAsync(array $args = [])
  128.  * @method \Aws\Result getObjectLockConfiguration(array $args = [])
  129.  * @method \GuzzleHttp\Promise\Promise getObjectLockConfigurationAsync(array $args = [])
  130.  * @method \Aws\Result getObjectRetention(array $args = [])
  131.  * @method \GuzzleHttp\Promise\Promise getObjectRetentionAsync(array $args = [])
  132.  * @method \Aws\Result getObjectTagging(array $args = [])
  133.  * @method \GuzzleHttp\Promise\Promise getObjectTaggingAsync(array $args = [])
  134.  * @method \Aws\Result getObjectTorrent(array $args = [])
  135.  * @method \GuzzleHttp\Promise\Promise getObjectTorrentAsync(array $args = [])
  136.  * @method \Aws\Result getPublicAccessBlock(array $args = [])
  137.  * @method \GuzzleHttp\Promise\Promise getPublicAccessBlockAsync(array $args = [])
  138.  * @method \Aws\Result headBucket(array $args = [])
  139.  * @method \GuzzleHttp\Promise\Promise headBucketAsync(array $args = [])
  140.  * @method \Aws\Result headObject(array $args = [])
  141.  * @method \GuzzleHttp\Promise\Promise headObjectAsync(array $args = [])
  142.  * @method \Aws\Result listBucketAnalyticsConfigurations(array $args = [])
  143.  * @method \GuzzleHttp\Promise\Promise listBucketAnalyticsConfigurationsAsync(array $args = [])
  144.  * @method \Aws\Result listBucketIntelligentTieringConfigurations(array $args = [])
  145.  * @method \GuzzleHttp\Promise\Promise listBucketIntelligentTieringConfigurationsAsync(array $args = [])
  146.  * @method \Aws\Result listBucketInventoryConfigurations(array $args = [])
  147.  * @method \GuzzleHttp\Promise\Promise listBucketInventoryConfigurationsAsync(array $args = [])
  148.  * @method \Aws\Result listBucketMetricsConfigurations(array $args = [])
  149.  * @method \GuzzleHttp\Promise\Promise listBucketMetricsConfigurationsAsync(array $args = [])
  150.  * @method \Aws\Result listBuckets(array $args = [])
  151.  * @method \GuzzleHttp\Promise\Promise listBucketsAsync(array $args = [])
  152.  * @method \Aws\Result listMultipartUploads(array $args = [])
  153.  * @method \GuzzleHttp\Promise\Promise listMultipartUploadsAsync(array $args = [])
  154.  * @method \Aws\Result listObjectVersions(array $args = [])
  155.  * @method \GuzzleHttp\Promise\Promise listObjectVersionsAsync(array $args = [])
  156.  * @method \Aws\Result listObjects(array $args = [])
  157.  * @method \GuzzleHttp\Promise\Promise listObjectsAsync(array $args = [])
  158.  * @method \Aws\Result listObjectsV2(array $args = [])
  159.  * @method \GuzzleHttp\Promise\Promise listObjectsV2Async(array $args = [])
  160.  * @method \Aws\Result listParts(array $args = [])
  161.  * @method \GuzzleHttp\Promise\Promise listPartsAsync(array $args = [])
  162.  * @method \Aws\Result putBucketAccelerateConfiguration(array $args = [])
  163.  * @method \GuzzleHttp\Promise\Promise putBucketAccelerateConfigurationAsync(array $args = [])
  164.  * @method \Aws\Result putBucketAcl(array $args = [])
  165.  * @method \GuzzleHttp\Promise\Promise putBucketAclAsync(array $args = [])
  166.  * @method \Aws\Result putBucketAnalyticsConfiguration(array $args = [])
  167.  * @method \GuzzleHttp\Promise\Promise putBucketAnalyticsConfigurationAsync(array $args = [])
  168.  * @method \Aws\Result putBucketCors(array $args = [])
  169.  * @method \GuzzleHttp\Promise\Promise putBucketCorsAsync(array $args = [])
  170.  * @method \Aws\Result putBucketEncryption(array $args = [])
  171.  * @method \GuzzleHttp\Promise\Promise putBucketEncryptionAsync(array $args = [])
  172.  * @method \Aws\Result putBucketIntelligentTieringConfiguration(array $args = [])
  173.  * @method \GuzzleHttp\Promise\Promise putBucketIntelligentTieringConfigurationAsync(array $args = [])
  174.  * @method \Aws\Result putBucketInventoryConfiguration(array $args = [])
  175.  * @method \GuzzleHttp\Promise\Promise putBucketInventoryConfigurationAsync(array $args = [])
  176.  * @method \Aws\Result putBucketLifecycle(array $args = [])
  177.  * @method \GuzzleHttp\Promise\Promise putBucketLifecycleAsync(array $args = [])
  178.  * @method \Aws\Result putBucketLifecycleConfiguration(array $args = [])
  179.  * @method \GuzzleHttp\Promise\Promise putBucketLifecycleConfigurationAsync(array $args = [])
  180.  * @method \Aws\Result putBucketLogging(array $args = [])
  181.  * @method \GuzzleHttp\Promise\Promise putBucketLoggingAsync(array $args = [])
  182.  * @method \Aws\Result putBucketMetricsConfiguration(array $args = [])
  183.  * @method \GuzzleHttp\Promise\Promise putBucketMetricsConfigurationAsync(array $args = [])
  184.  * @method \Aws\Result putBucketNotification(array $args = [])
  185.  * @method \GuzzleHttp\Promise\Promise putBucketNotificationAsync(array $args = [])
  186.  * @method \Aws\Result putBucketNotificationConfiguration(array $args = [])
  187.  * @method \GuzzleHttp\Promise\Promise putBucketNotificationConfigurationAsync(array $args = [])
  188.  * @method \Aws\Result putBucketOwnershipControls(array $args = [])
  189.  * @method \GuzzleHttp\Promise\Promise putBucketOwnershipControlsAsync(array $args = [])
  190.  * @method \Aws\Result putBucketPolicy(array $args = [])
  191.  * @method \GuzzleHttp\Promise\Promise putBucketPolicyAsync(array $args = [])
  192.  * @method \Aws\Result putBucketReplication(array $args = [])
  193.  * @method \GuzzleHttp\Promise\Promise putBucketReplicationAsync(array $args = [])
  194.  * @method \Aws\Result putBucketRequestPayment(array $args = [])
  195.  * @method \GuzzleHttp\Promise\Promise putBucketRequestPaymentAsync(array $args = [])
  196.  * @method \Aws\Result putBucketTagging(array $args = [])
  197.  * @method \GuzzleHttp\Promise\Promise putBucketTaggingAsync(array $args = [])
  198.  * @method \Aws\Result putBucketVersioning(array $args = [])
  199.  * @method \GuzzleHttp\Promise\Promise putBucketVersioningAsync(array $args = [])
  200.  * @method \Aws\Result putBucketWebsite(array $args = [])
  201.  * @method \GuzzleHttp\Promise\Promise putBucketWebsiteAsync(array $args = [])
  202.  * @method \Aws\Result putObject(array $args = [])
  203.  * @method \GuzzleHttp\Promise\Promise putObjectAsync(array $args = [])
  204.  * @method \Aws\Result putObjectAcl(array $args = [])
  205.  * @method \GuzzleHttp\Promise\Promise putObjectAclAsync(array $args = [])
  206.  * @method \Aws\Result putObjectLegalHold(array $args = [])
  207.  * @method \GuzzleHttp\Promise\Promise putObjectLegalHoldAsync(array $args = [])
  208.  * @method \Aws\Result putObjectLockConfiguration(array $args = [])
  209.  * @method \GuzzleHttp\Promise\Promise putObjectLockConfigurationAsync(array $args = [])
  210.  * @method \Aws\Result putObjectRetention(array $args = [])
  211.  * @method \GuzzleHttp\Promise\Promise putObjectRetentionAsync(array $args = [])
  212.  * @method \Aws\Result putObjectTagging(array $args = [])
  213.  * @method \GuzzleHttp\Promise\Promise putObjectTaggingAsync(array $args = [])
  214.  * @method \Aws\Result putPublicAccessBlock(array $args = [])
  215.  * @method \GuzzleHttp\Promise\Promise putPublicAccessBlockAsync(array $args = [])
  216.  * @method \Aws\Result restoreObject(array $args = [])
  217.  * @method \GuzzleHttp\Promise\Promise restoreObjectAsync(array $args = [])
  218.  * @method \Aws\Result selectObjectContent(array $args = [])
  219.  * @method \GuzzleHttp\Promise\Promise selectObjectContentAsync(array $args = [])
  220.  * @method \Aws\Result uploadPart(array $args = [])
  221.  * @method \GuzzleHttp\Promise\Promise uploadPartAsync(array $args = [])
  222.  * @method \Aws\Result uploadPartCopy(array $args = [])
  223.  * @method \GuzzleHttp\Promise\Promise uploadPartCopyAsync(array $args = [])
  224.  * @method \Aws\Result writeGetObjectResponse(array $args = [])
  225.  * @method \GuzzleHttp\Promise\Promise writeGetObjectResponseAsync(array $args = [])
  226.  */
  227. class S3Client extends AwsClient implements S3ClientInterface
  228. {
  229.     use S3ClientTrait;
  231.     /** @var array */
  232.     private static $mandatoryAttributes = ['Bucket', 'Key'];
  234.     public static function getArguments()
  235.     {
  236.         $args = parent::getArguments();
  237.         $args['retries']['fn'] = [__CLASS__, '_applyRetryConfig'];
  238.         $args['api_provider']['fn'] = [__CLASS__, '_applyApiProvider'];
  240.         return $args + [
  241.             'bucket_endpoint' => [
  242.                 'type'    => 'config',
  243.                 'valid'   => ['bool'],
  244.                 'doc'     => 'Set to true to send requests to a hardcoded '
  245.                     . 'bucket endpoint rather than create an endpoint as a '
  246.                     . 'result of injecting the bucket into the URL. This '
  247.                     . 'option is useful for interacting with CNAME endpoints.',
  248.             ],
  249.             'use_arn_region' => [
  250.                 'type'    => 'config',
  251.                 'valid'   => [
  252.                     'bool',
  253.                     Configuration::class,
  254.                     CacheInterface::class,
  255.                     'callable'
  256.                 ],
  257.                 'doc'     => 'Set to true to allow passed in ARNs to override'
  258.                     . ' client region. Accepts...',
  259.                 'fn' => [__CLASS__, '_apply_use_arn_region'],
  260.                 'default' => [UseArnRegionConfigurationProvider::class, 'defaultProvider'],
  261.             ],
  262.             'use_accelerate_endpoint' => [
  263.                 'type' => 'config',
  264.                 'valid' => ['bool'],
  265.                 'doc' => 'Set to true to send requests to an S3 Accelerate'
  266.                     . ' endpoint by default. Can be enabled or disabled on'
  267.                     . ' individual operations by setting'
  268.                     . ' \'@use_accelerate_endpoint\' to true or false. Note:'
  269.                     . ' you must enable S3 Accelerate on a bucket before it can'
  270.                     . ' be accessed via an Accelerate endpoint.',
  271.                 'default' => false,
  272.             ],
  273.             'use_path_style_endpoint' => [
  274.                 'type' => 'config',
  275.                 'valid' => ['bool'],
  276.                 'doc' => 'Set to true to send requests to an S3 path style'
  277.                     . ' endpoint by default.'
  278.                     . ' Can be enabled or disabled on individual operations by setting'
  279.                     . ' \'@use_path_style_endpoint\' to true or false.',
  280.                 'default' => false,
  281.             ],
  282.             'disable_multiregion_access_points' => [
  283.                 'type' => 'config',
  284.                 'valid' => ['bool'],
  285.                 'doc' => 'Set to true to disable the usage of'
  286.                     . ' multi region access points. These are enabled by default.'
  287.                     . ' Can be enabled or disabled on individual operations by setting'
  288.                     . ' \'@disable_multiregion_access_points\' to true or false.',
  289.                 'default' => false,
  290.             ],
  291.         ];
  292.     }
  294.     /**
  295.      * {@inheritdoc}
  296.      *
  297.      * In addition to the options available to
  298.      * {@see Aws\AwsClient::__construct}, S3Client accepts the following
  299.      * options:
  300.      *
  301.      * - bucket_endpoint: (bool) Set to true to send requests to a
  302.      *   hardcoded bucket endpoint rather than create an endpoint as a result
  303.      *   of injecting the bucket into the URL. This option is useful for
  304.      *   interacting with CNAME endpoints.
  305.      * - calculate_md5: (bool) Set to false to disable calculating an MD5
  306.      *   for all Amazon S3 signed uploads.
  307.      * - s3_us_east_1_regional_endpoint:
  308.      *   (Aws\S3\RegionalEndpoint\ConfigurationInterface|Aws\CacheInterface\|callable|string|array)
  309.      *   Specifies whether to use regional or legacy endpoints for the us-east-1
  310.      *   region. Provide an Aws\S3\RegionalEndpoint\ConfigurationInterface object, an
  311.      *   instance of Aws\CacheInterface, a callable configuration provider used
  312.      *   to create endpoint configuration, a string value of `legacy` or
  313.      *   `regional`, or an associative array with the following keys:
  314.      *   endpoint_types: (string)  Set to `legacy` or `regional`, defaults to
  315.      *   `legacy`
  316.      * - use_accelerate_endpoint: (bool) Set to true to send requests to an S3
  317.      *   Accelerate endpoint by default. Can be enabled or disabled on
  318.      *   individual operations by setting '@use_accelerate_endpoint' to true or
  319.      *   false. Note: you must enable S3 Accelerate on a bucket before it can be
  320.      *   accessed via an Accelerate endpoint.
  321.      * - use_arn_region: (Aws\S3\UseArnRegion\ConfigurationInterface,
  322.      *   Aws\CacheInterface, bool, callable) Set to true to enable the client
  323.      *   to use the region from a supplied ARN argument instead of the client's
  324.      *   region. Provide an instance of Aws\S3\UseArnRegion\ConfigurationInterface,
  325.      *   an instance of Aws\CacheInterface, a callable that provides a promise for
  326.      *   a Configuration object, or a boolean value. Defaults to false (i.e.
  327.      *   the SDK will not follow the ARN region if it conflicts with the client
  328.      *   region and instead throw an error).
  329.      * - use_dual_stack_endpoint: (bool) Set to true to send requests to an S3
  330.      *   Dual Stack endpoint by default, which enables IPv6 Protocol.
  331.      *   Can be enabled or disabled on individual operations by setting
  332.      *   '@use_dual_stack_endpoint\' to true or false. Note:
  333.      *   you cannot use it together with an accelerate endpoint.
  334.      * - use_path_style_endpoint: (bool) Set to true to send requests to an S3
  335.      *   path style endpoint by default.
  336.      *   Can be enabled or disabled on individual operations by setting
  337.      *   '@use_path_style_endpoint\' to true or false. Note:
  338.      *   you cannot use it together with an accelerate endpoint.
  339.      * - disable_multiregion_access_points: (bool) Set to true to disable
  340.      *   sending multi region requests.  They are enabled by default.
  341.      *   Can be enabled or disabled on individual operations by setting
  342.      *   '@disable_multiregion_access_points\' to true or false. Note:
  343.      *   you cannot use it together with an accelerate or dualstack endpoint.
  344.      *
  345.      * @param array $args
  346.      */
  347.     public function __construct(array $args)
  348.     {
  349.         if (
  350.             !isset($args['s3_us_east_1_regional_endpoint'])
  351.             || $args['s3_us_east_1_regional_endpoint'] instanceof CacheInterface
  352.         ) {
  353.             $args['s3_us_east_1_regional_endpoint'] = ConfigurationProvider::defaultProvider($args);
  354.         }
  355.         parent::__construct($args);
  356.         $stack = $this->getHandlerList();
  357.         $stack->appendInit(SSECMiddleware::wrap($this->getEndpoint()->getScheme()), 's3.ssec');
  358.         $stack->appendBuild(ApplyChecksumMiddleware::wrap($this->getApi()), 's3.checksum');
  359.         $stack->appendBuild(
  360.             Middleware::contentType(['PutObject', 'UploadPart']),
  361.             's3.content_type'
  362.         );
  364.         // Use the bucket style middleware when using a "bucket_endpoint" (for cnames)
  365.         if ($this->getConfig('bucket_endpoint')) {
  366.             $stack->appendBuild(BucketEndpointMiddleware::wrap(), 's3.bucket_endpoint');
  367.         } else {
  368.             $stack->appendBuild(
  369.                 S3EndpointMiddleware::wrap(
  370.                     $this->getRegion(),
  371.                     $this->getConfig('endpoint_provider'),
  372.                     [
  373.                         'accelerate' => $this->getConfig('use_accelerate_endpoint'),
  374.                         'path_style' => $this->getConfig('use_path_style_endpoint'),
  375.                         'use_fips_endpoint' => $this->getConfig('use_fips_endpoint'),
  376.                         'dual_stack' =>
  377.                             $this->getConfig('use_dual_stack_endpoint')->isUseDualStackEndpoint(),
  379.                     ]
  380.                 ),
  381.                 's3.endpoint_middleware'
  382.             );
  383.         }
  385.         $stack->appendBuild(
  386.             BucketEndpointArnMiddleware::wrap(
  387.                 $this->getApi(),
  388.                 $this->getRegion(),
  389.                 [
  390.                     'use_arn_region' => $this->getConfig('use_arn_region'),
  391.                     'accelerate' => $this->getConfig('use_accelerate_endpoint'),
  392.                     'path_style' => $this->getConfig('use_path_style_endpoint'),
  393.                     'dual_stack' =>
  394.                         $this->getConfig('use_dual_stack_endpoint')->isUseDualStackEndpoint(),
  395.                     'use_fips_endpoint' => $this->getConfig('use_fips_endpoint'),
  396.                     'disable_multiregion_access_points' =>
  397.                         $this->getConfig('disable_multiregion_access_points'),
  398.                     'endpoint' => isset($args['endpoint'])
  399.                         ? $args['endpoint']
  400.                         : null
  401.                 ]
  402.             ),
  403.             's3.bucket_endpoint_arn'
  404.         );
  406.         $stack->appendValidate(
  407.             InputValidationMiddleware::wrap($this->getApi(), self::$mandatoryAttributes),
  408.             'input_validation_middleware'
  409.         );
  410.         $stack->appendSign(PutObjectUrlMiddleware::wrap(), 's3.put_object_url');
  411.         $stack->appendSign(PermanentRedirectMiddleware::wrap(), 's3.permanent_redirect');
  412.         $stack->appendInit(Middleware::sourceFile($this->getApi()), 's3.source_file');
  413.         $stack->appendInit($this->getSaveAsParameter(), 's3.save_as');
  414.         $stack->appendInit($this->getLocationConstraintMiddleware(), 's3.location');
  415.         $stack->appendInit($this->getEncodingTypeMiddleware(), 's3.auto_encode');
  416.         $stack->appendInit($this->getHeadObjectMiddleware(), 's3.head_object');
  417.     }
  419.     /**
  420.      * Determine if a string is a valid name for a DNS compatible Amazon S3
  421.      * bucket.
  422.      *
  423.      * DNS compatible bucket names can be used as a subdomain in a URL (e.g.,
  424.      * "<bucket>.s3.amazonaws.com").
  425.      *
  426.      * @param string $bucket Bucket name to check.
  427.      *
  428.      * @return bool
  429.      */
  430.     public static function isBucketDnsCompatible($bucket)
  431.     {
  432.         $bucketLen = strlen($bucket);
  434.         return ($bucketLen >= 3 && $bucketLen <= 63) &&
  435.             // Cannot look like an IP address
  436.             !filter_var($bucket, FILTER_VALIDATE_IP) &&
  437.             preg_match('/^[a-z0-9]([a-z0-9\-\.]*[a-z0-9])?$/', $bucket);
  438.     }
  440.     public static function _apply_use_arn_region($value, array &$args, HandlerList $list)
  441.     {
  442.         if ($value instanceof CacheInterface) {
  443.             $value = UseArnRegionConfigurationProvider::defaultProvider($args);
  444.         }
  445.         if (is_callable($value)) {
  446.             $value = $value();
  447.         }
  448.         if ($value instanceof PromiseInterface) {
  449.             $value = $value->wait();
  450.         }
  451.         if ($value instanceof ConfigurationInterface) {
  452.             $args['use_arn_region'] = $value;
  453.         } else {
  454.             // The Configuration class itself will validate other inputs
  455.             $args['use_arn_region'] = new Configuration($value);
  456.         }
  457.     }
  459.     public function createPresignedRequest(CommandInterface $command, $expires, array $options = [])
  460.     {
  461.         $command = clone $command;
  462.         $command->getHandlerList()->remove('signer');
  464.         /** @var \Aws\Signature\SignatureInterface $signer */
  465.         $signer = call_user_func(
  466.             $this->getSignatureProvider(),
  467.             $this->getConfig('signature_version'),
  468.             $this->getConfig('signing_name'),
  469.             $this->getConfig('signing_region')
  470.         );
  472.         return $signer->presign(
  473.             \Aws\serialize($command),
  474.             $this->getCredentials()->wait(),
  475.             $expires,
  476.             $options
  477.         );
  478.     }
  480.     /**
  481.      * Returns the URL to an object identified by its bucket and key.
  482.      *
  483.      * The URL returned by this method is not signed nor does it ensure that the
  484.      * bucket and key given to the method exist. If you need a signed URL, then
  485.      * use the {@see \Aws\S3\S3Client::createPresignedRequest} method and get
  486.      * the URI of the signed request.
  487.      *
  488.      * @param string $bucket  The name of the bucket where the object is located
  489.      * @param string $key     The key of the object
  490.      *
  491.      * @return string The URL to the object
  492.      */
  493.     public function getObjectUrl($bucket, $key)
  494.     {
  495.         $command = $this->getCommand('GetObject', [
  496.             'Bucket' => $bucket,
  497.             'Key'    => $key
  498.         ]);
  500.         return (string) \Aws\serialize($command)->getUri();
  501.     }
  503.     /**
  504.      * Raw URL encode a key and allow for '/' characters
  505.      *
  506.      * @param string $key Key to encode
  507.      *
  508.      * @return string Returns the encoded key
  509.      */
  510.     public static function encodeKey($key)
  511.     {
  512.         return str_replace('%2F', '/', rawurlencode($key));
  513.     }
  515.     /**
  516.      * Provides a middleware that removes the need to specify LocationConstraint on CreateBucket.
  517.      *
  518.      * @return \Closure
  519.      */
  520.     private function getLocationConstraintMiddleware()
  521.     {
  522.         $region = $this->getRegion();
  523.         return static function (callable $handler) use ($region) {
  524.             return function (Command $command, $request = null) use ($handler, $region) {
  525.                 if ($command->getName() === 'CreateBucket') {
  526.                     $locationConstraint = isset($command['CreateBucketConfiguration']['LocationConstraint'])
  527.                         ? $command['CreateBucketConfiguration']['LocationConstraint']
  528.                         : null;
  530.                     if ($locationConstraint === 'us-east-1') {
  531.                         unset($command['CreateBucketConfiguration']);
  532.                     } elseif ('us-east-1' !== $region && empty($locationConstraint)) {
  533.                         $command['CreateBucketConfiguration'] = ['LocationConstraint' => $region];
  534.                     }
  535.                 }
  537.                 return $handler($command, $request);
  538.             };
  539.         };
  540.     }
  542.     /**
  543.      * Provides a middleware that supports the `SaveAs` parameter.
  544.      *
  545.      * @return \Closure
  546.      */
  547.     private function getSaveAsParameter()
  548.     {
  549.         return static function (callable $handler) {
  550.             return function (Command $command, $request = null) use ($handler) {
  551.                 if ($command->getName() === 'GetObject' && isset($command['SaveAs'])) {
  552.                     $command['@http']['sink'] = $command['SaveAs'];
  553.                     unset($command['SaveAs']);
  554.                 }
  556.                 return $handler($command, $request);
  557.             };
  558.         };
  559.     }
  561.     /**
  562.      * Provides a middleware that disables content decoding on HeadObject
  563.      * commands.
  564.      *
  565.      * @return \Closure
  566.      */
  567.     private function getHeadObjectMiddleware()
  568.     {
  569.         return static function (callable $handler) {
  570.             return function (
  571.                 CommandInterface $command,
  572.                 RequestInterface $request = null
  573.             ) use ($handler) {
  574.                 if ($command->getName() === 'HeadObject'
  575.                     && !isset($command['@http']['decode_content'])
  576.                 ) {
  577.                     $command['@http']['decode_content'] = false;
  578.                 }
  580.                 return $handler($command, $request);
  581.             };
  582.         };
  583.     }
  585.     /**
  586.      * Provides a middleware that autopopulates the EncodingType parameter on
  587.      * ListObjects commands.
  588.      *
  589.      * @return \Closure
  590.      */
  591.     private function getEncodingTypeMiddleware()
  592.     {
  593.         return static function (callable $handler) {
  594.             return function (Command $command, $request = null) use ($handler) {
  595.                 $autoSet = false;
  596.                 if ($command->getName() === 'ListObjects'
  597.                     && empty($command['EncodingType'])
  598.                 ) {
  599.                     $command['EncodingType'] = 'url';
  600.                     $autoSet = true;
  601.                 }
  603.                 return $handler($command, $request)
  604.                     ->then(function (ResultInterface $result) use ($autoSet) {
  605.                         if ($result['EncodingType'] === 'url' && $autoSet) {
  606.                             static $topLevel = [
  607.                                 'Delimiter',
  608.                                 'Marker',
  609.                                 'NextMarker',
  610.                                 'Prefix',
  611.                             ];
  612.                             static $nested = [
  613.                                 ['Contents', 'Key'],
  614.                                 ['CommonPrefixes', 'Prefix'],
  615.                             ];
  617.                             foreach ($topLevel as $key) {
  618.                                 if (isset($result[$key])) {
  619.                                     $result[$key] = urldecode($result[$key]);
  620.                                 }
  621.                             }
  622.                             foreach ($nested as $steps) {
  623.                                 if (isset($result[$steps[0]])) {
  624.                                     foreach ($result[$steps[0]] as $key => $part) {
  625.                                         if (isset($part[$steps[1]])) {
  626.                                             $result[$steps[0]][$key][$steps[1]]
  627.                                                 = urldecode($part[$steps[1]]);
  628.                                         }
  629.                                     }
  630.                                 }
  631.                             }
  633.                         }
  635.                         return $result;
  636.                     });
  637.             };
  638.         };
  639.     }
  641.     /** @internal */
  642.     public static function _applyRetryConfig($value, $args, HandlerList $list)
  643.     {
  644.         if ($value) {
  645.             $config = \Aws\Retry\ConfigurationProvider::unwrap($value);
  647.             if ($config->getMode() === 'legacy') {
  648.                 $maxRetries = $config->getMaxAttempts() - 1;
  649.                 $decider = RetryMiddleware::createDefaultDecider($maxRetries);
  650.                 $decider = function ($retries, $command, $request, $result, $error) use ($decider, $maxRetries) {
  651.                     $maxRetries = null !== $command['@retries']
  652.                         ? $command['@retries']
  653.                         : $maxRetries;
  655.                     if ($decider($retries, $command, $request, $result, $error)) {
  656.                         return true;
  657.                     }
  659.                     if ($error instanceof AwsException
  660.                         && $retries < $maxRetries
  661.                     ) {
  662.                         if ($error->getResponse()
  663.                             && $error->getResponse()->getStatusCode() >= 400
  664.                         ) {
  665.                             return strpos(
  666.                                     $error->getResponse()->getBody(),
  667.                                     'Your socket connection to the server'
  668.                                 ) !== false;
  669.                         }
  671.                         if ($error->getPrevious() instanceof RequestException) {
  672.                             // All commands except CompleteMultipartUpload are
  673.                             // idempotent and may be retried without worry if a
  674.                             // networking error has occurred.
  675.                             return $command->getName() !== 'CompleteMultipartUpload';
  676.                         }
  677.                     }
  679.                     return false;
  680.                 };
  682.                 $delay = [RetryMiddleware::class, 'exponentialDelay'];
  683.                 $list->appendSign(Middleware::retry($decider, $delay), 'retry');
  684.             } else {
  685.                 $defaultDecider = RetryMiddlewareV2::createDefaultDecider(
  686.                     new QuotaManager(),
  687.                     $config->getMaxAttempts()
  688.                 );
  690.                 $list->appendSign(
  691.                     RetryMiddlewareV2::wrap(
  692.                         $config,
  693.                         [
  694.                             'collect_stats' => $args['stats']['retries'],
  695.                             'decider' => function(
  696.                                 $attempts,
  697.                                 CommandInterface $cmd,
  698.                                 $result
  699.                             ) use ($defaultDecider, $config) {
  700.                                 $isRetryable = $defaultDecider($attempts, $cmd, $result);
  701.                                 if (!$isRetryable
  702.                                     && $result instanceof AwsException
  703.                                     && $attempts < $config->getMaxAttempts()
  704.                                 ) {
  705.                                     if (!empty($result->getResponse())
  706.                                         && strpos(
  707.                                             $result->getResponse()->getBody(),
  708.                                             'Your socket connection to the server'
  709.                                         ) !== false
  710.                                     ) {
  711.                                         $isRetryable = false;
  712.                                     }
  713.                                     if ($result->getPrevious() instanceof RequestException
  714.                                         && $cmd->getName() !== 'CompleteMultipartUpload'
  715.                                     ) {
  716.                                         $isRetryable = true;
  717.                                     }
  718.                                 }
  719.                                 return $isRetryable;
  720.                             }
  721.                         ]
  722.                     ),
  723.                     'retry'
  724.                 );
  725.             }
  726.         }
  727.     }
  729.     /** @internal */
  730.     public static function _applyApiProvider($value, array &$args, HandlerList $list)
  731.     {
  732.         ClientResolver::_apply_api_provider($value, $args);
  733.         $args['parser'] = new GetBucketLocationParser(
  734.             new ValidateResponseChecksumParser(
  735.                 new AmbiguousSuccessParser(
  736.                     new RetryableMalformedResponseParser(
  737.                         $args['parser'],
  738.                         $args['exception_class']
  739.                     ),
  740.                     $args['error_parser'],
  741.                     $args['exception_class']
  742.                 ),
  743.                 $args['api']
  744.             )
  745.         );
  746.     }
  748.     /**
  749.      * @internal
  750.      * @codeCoverageIgnore
  751.      */
  752.     public static function applyDocFilters(array $api, array $docs)
  753.     {
  754.         $b64 = '<div class="alert alert-info">This value will be base64 encoded on your behalf.</div>';
  755.         $opt = '<div class="alert alert-info">This value will be computed for you it is not supplied.</div>';
  757.         // Add a note on the CopyObject docs
  758.          $s3ExceptionRetryMessage = "<p>Additional info on response behavior: if there is"
  759.             . " an internal error in S3 after the request was successfully recieved,"
  760.             . " a 200 response will be returned with an <code>S3Exception</code> embedded"
  761.             . " in it; this will still be caught and retried by"
  762.             . " <code>RetryMiddleware.</code></p>";
  764.         $docs['operations']['CopyObject'] .=  $s3ExceptionRetryMessage;
  765.         $docs['operations']['CompleteMultipartUpload'] .=  $s3ExceptionRetryMessage;
  766.         $docs['operations']['UploadPartCopy'] .=  $s3ExceptionRetryMessage;
  767.         $docs['operations']['UploadPart'] .=  $s3ExceptionRetryMessage;
  769.         // Add note about stream ownership in the putObject call
  770.         $guzzleStreamMessage = "<p>Additional info on behavior of the stream"
  771.             . " parameters: Psr7 takes ownership of streams and will automatically close"
  772.             . " streams when this method is called with a stream as the <code>Body</code>"
  773.             . " parameter.  To prevent this, set the <code>Body</code> using"
  774.             . " <code>GuzzleHttp\Psr7\stream_for</code> method with a is an instance of"
  775.             . " <code>Psr\Http\Message\StreamInterface</code>, and it will be returned"
  776.             . " unmodified. This will allow you to keep the stream in scope. </p>";
  777.         $docs['operations']['PutObject'] .=  $guzzleStreamMessage;
  779.         // Add the SourceFile parameter.
  780.         $docs['shapes']['SourceFile']['base'] = 'The path to a file on disk to use instead of the Body parameter.';
  781.         $api['shapes']['SourceFile'] = ['type' => 'string'];
  782.         $api['shapes']['PutObjectRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
  783.         $api['shapes']['UploadPartRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
  785.         // Add the ContentSHA256 parameter.
  786.         $docs['shapes']['ContentSHA256']['base'] = 'A SHA256 hash of the body content of the request.';
  787.         $api['shapes']['ContentSHA256'] = ['type' => 'string'];
  788.         $api['shapes']['PutObjectRequest']['members']['ContentSHA256'] = ['shape' => 'ContentSHA256'];
  789.         $api['shapes']['UploadPartRequest']['members']['ContentSHA256'] = ['shape' => 'ContentSHA256'];
  790.         unset($api['shapes']['PutObjectRequest']['members']['ContentMD5']);
  791.         unset($api['shapes']['UploadPartRequest']['members']['ContentMD5']);
  792.         $docs['shapes']['ContentSHA256']['append'] = $opt;
  794.         // Add the SaveAs parameter.
  795.         $docs['shapes']['SaveAs']['base'] = 'The path to a file on disk to save the object data.';
  796.         $api['shapes']['SaveAs'] = ['type' => 'string'];
  797.         $api['shapes']['GetObjectRequest']['members']['SaveAs'] = ['shape' => 'SaveAs'];
  799.         // Several SSECustomerKey documentation updates.
  800.         $docs['shapes']['SSECustomerKey']['append'] = $b64;
  801.         $docs['shapes']['CopySourceSSECustomerKey']['append'] = $b64;
  802.         $docs['shapes']['SSECustomerKeyMd5']['append'] = $opt;
  804.         // Add the ObjectURL to various output shapes and documentation.
  805.         $docs['shapes']['ObjectURL']['base'] = 'The URI of the created object.';
  806.         $api['shapes']['ObjectURL'] = ['type' => 'string'];
  807.         $api['shapes']['PutObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
  808.         $api['shapes']['CopyObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
  809.         $api['shapes']['CompleteMultipartUploadOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
  811.         // Fix references to Location Constraint.
  812.         unset($api['shapes']['CreateBucketRequest']['payload']);
  813.         $api['shapes']['BucketLocationConstraint']['enum'] = [
  814.             "ap-northeast-1",
  815.             "ap-southeast-2",
  816.             "ap-southeast-1",
  817.             "cn-north-1",
  818.             "eu-central-1",
  819.             "eu-west-1",
  820.             "us-east-1",
  821.             "us-west-1",
  822.             "us-west-2",
  823.             "sa-east-1",
  824.         ];
  826.         // Add a note that the ContentMD5 is optional.
  827.         $docs['shapes']['ContentMD5']['append'] = '<div class="alert alert-info">The value will be computed on '
  828.             . 'your behalf.</div>';
  830.         return [
  831.             new Service($api, ApiProvider::defaultProvider()),
  832.             new DocModel($docs)
  833.         ];
  834.     }
  836.     /**
  837.      * @internal
  838.      * @codeCoverageIgnore
  839.      */
  840.     public static function addDocExamples($examples)
  841.     {
  842.         $getObjectExample = [
  843.             'input' => [
  844.                 'Bucket' => 'arn:aws:s3:us-east-1:123456789012:accesspoint:myaccesspoint',
  845.                 'Key' => 'my-key'
  846.             ],
  847.             'output' => [
  848.                 'Body' => 'class GuzzleHttp\Psr7\Stream#208 (7) {...}',
  849.                 'ContentLength' => '11',
  850.                 'ContentType' => 'application/octet-stream',
  851.             ],
  852.             'comments' => [
  853.                 'input' => '',
  854.                 'output' => 'Simplified example output'
  855.             ],
  856.             'description' => 'The following example retrieves an object by referencing the bucket via an S3 accesss point ARN. Result output is simplified for the example.',
  857.             'id' => '',
  858.             'title' => 'To get an object via an S3 access point ARN'
  859.         ];
  860.         if (isset($examples['GetObject'])) {
  861.             $examples['GetObject'] []= $getObjectExample;
  862.         } else {
  863.             $examples['GetObject'] = [$getObjectExample];
  864.         }
  866.         $putObjectExample = [
  867.             'input' => [
  868.                 'Bucket' => 'arn:aws:s3:us-east-1:123456789012:accesspoint:myaccesspoint',
  869.                 'Key' => 'my-key',
  870.                 'Body' => 'my-body',
  871.             ],
  872.             'output' => [
  873.                 'ObjectURL' => 'https://my-bucket.s3.us-east-1.amazonaws.com/my-key'
  874.             ],
  875.             'comments' => [
  876.                 'input' => '',
  877.                 'output' => 'Simplified example output'
  878.             ],
  879.             'description' => 'The following example uploads an object by referencing the bucket via an S3 accesss point ARN. Result output is simplified for the example.',
  880.             'id' => '',
  881.             'title' => 'To upload an object via an S3 access point ARN'
  882.         ];
  883.         if (isset($examples['PutObject'])) {
  884.             $examples['PutObject'] []= $putObjectExample;
  885.         } else {
  886.             $examples['PutObject'] = [$putObjectExample];
  887.         }
  889.         return $examples;
  890.     }
  891. }