in src/S3/S3Client.php [1113:1233]
public static function applyDocFilters(array $api, array $docs)
{
$b64 = '<div class="alert alert-info">This value will be base64 encoded on your behalf.</div>';
$opt = '<div class="alert alert-info">This value will be computed for you it is not supplied.</div>';
// Add a note on the CopyObject docs
$s3ExceptionRetryMessage = "<p>Additional info on response behavior: if there is"
. " an internal error in S3 after the request was successfully recieved,"
. " a 200 response will be returned with an <code>S3Exception</code> embedded"
. " in it; this will still be caught and retried by"
. " <code>RetryMiddleware.</code></p>";
$docs['operations']['CopyObject'] .= $s3ExceptionRetryMessage;
$docs['operations']['CompleteMultipartUpload'] .= $s3ExceptionRetryMessage;
$docs['operations']['UploadPartCopy'] .= $s3ExceptionRetryMessage;
$docs['operations']['UploadPart'] .= $s3ExceptionRetryMessage;
// Add note about stream ownership in the putObject call
$guzzleStreamMessage = "<p>Additional info on behavior of the stream"
. " parameters: Psr7 takes ownership of streams and will automatically close"
. " streams when this method is called with a stream as the <code>Body</code>"
. " parameter. To prevent this, set the <code>Body</code> using"
. " <code>GuzzleHttp\Psr7\stream_for</code> method with a is an instance of"
. " <code>Psr\Http\Message\StreamInterface</code>, and it will be returned"
. " unmodified. This will allow you to keep the stream in scope. </p>";
$docs['operations']['PutObject'] .= $guzzleStreamMessage;
// Add the SourceFile parameter.
$docs['shapes']['SourceFile']['base'] = 'The path to a file on disk to use instead of the Body parameter.';
$api['shapes']['SourceFile'] = ['type' => 'string'];
$api['shapes']['PutObjectRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
$api['shapes']['UploadPartRequest']['members']['SourceFile'] = ['shape' => 'SourceFile'];
// Add the ContentSHA256 parameter.
$docs['shapes']['ContentSHA256']['base'] = 'A SHA256 hash of the body content of the request.';
$api['shapes']['ContentSHA256'] = ['type' => 'string'];
$api['shapes']['PutObjectRequest']['members']['ContentSHA256'] = ['shape' => 'ContentSHA256'];
$api['shapes']['UploadPartRequest']['members']['ContentSHA256'] = ['shape' => 'ContentSHA256'];
$docs['shapes']['ContentSHA256']['append'] = $opt;
// Add the AddContentMD5 parameter.
$docs['shapes']['AddContentMD5']['base'] = 'Set to true to calculate the ContentMD5 for the upload.';
$api['shapes']['AddContentMD5'] = ['type' => 'boolean'];
$api['shapes']['PutObjectRequest']['members']['AddContentMD5'] = ['shape' => 'AddContentMD5'];
$api['shapes']['UploadPartRequest']['members']['AddContentMD5'] = ['shape' => 'AddContentMD5'];
// Add the SaveAs parameter.
$docs['shapes']['SaveAs']['base'] = 'The path to a file on disk to save the object data.';
$api['shapes']['SaveAs'] = ['type' => 'string'];
$api['shapes']['GetObjectRequest']['members']['SaveAs'] = ['shape' => 'SaveAs'];
// Several SSECustomerKey documentation updates.
$docs['shapes']['SSECustomerKey']['append'] = $b64;
$docs['shapes']['CopySourceSSECustomerKey']['append'] = $b64;
$docs['shapes']['SSECustomerKeyMd5']['append'] = $opt;
// Add the ObjectURL to various output shapes and documentation.
$docs['shapes']['ObjectURL']['base'] = 'The URI of the created object.';
$api['shapes']['ObjectURL'] = ['type' => 'string'];
$api['shapes']['PutObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
$api['shapes']['CopyObjectOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
$api['shapes']['CompleteMultipartUploadOutput']['members']['ObjectURL'] = ['shape' => 'ObjectURL'];
// Fix references to Location Constraint.
unset($api['shapes']['CreateBucketRequest']['payload']);
$api['shapes']['BucketLocationConstraint']['enum'] = [
"ap-northeast-1",
"ap-southeast-2",
"ap-southeast-1",
"cn-north-1",
"eu-central-1",
"eu-west-1",
"us-east-1",
"us-west-1",
"us-west-2",
"sa-east-1",
];
// Add a note that the ContentMD5 is automatically computed, except for with PutObject and UploadPart
$docs['shapes']['ContentMD5']['append'] = '<div class="alert alert-info">The value will be computed on '
. 'your behalf.</div>';
$docs['shapes']['ContentMD5']['excludeAppend'] = ['PutObjectRequest', 'UploadPartRequest'];
//Add a note to ContentMD5 for PutObject and UploadPart that specifies the value is required
// When uploading to a bucket with object lock enabled and that it is not computed automatically
$objectLock = '<div class="alert alert-info">This value is required if uploading to a bucket '
. 'which has Object Lock enabled. It will not be calculated for you automatically. If you wish to have '
. 'the value calculated for you, use the `AddContentMD5` parameter.</div>';
$docs['shapes']['ContentMD5']['appendOnly'] = [
'message' => $objectLock,
'shapes' => ['PutObjectRequest', 'UploadPartRequest']
];
// Add `ExpiresString` shape to output structures which contain `Expires`
// Deprecate existing `Expires` shapes in output structures
// Add/Update documentation for both `ExpiresString` and `Expires`
// Ensure `Expires` type remains timestamp
foreach ($api['shapes'] as $key => &$value) {
$suffix = 'Output';
if (substr($key, -strlen($suffix)) === $suffix) {
if (isset($value['members']['Expires'])) {
$value['members']['Expires']['deprecated'] = true;
$value['members']['ExpiresString'] = [
'shape' => 'ExpiresString',
'location' => 'header',
'locationName' => 'Expires'
];
$docs['shapes']['Expires']['refs'][$key . '$Expires']
.= '<p>This output shape has been deprecated. Please refer to <code>ExpiresString</code> instead.</p>.';
}
}
}
$api['shapes']['ExpiresString']['type'] = 'string';
$docs['shapes']['ExpiresString']['base'] = 'The unparsed string value of the <code>Expires</code> output member.';
$api['shapes']['Expires']['type'] = 'timestamp';
return [
new Service($api, ApiProvider::defaultProvider()),
new DocModel($docs)
];
}