media-cloud-sync / includes / sdk / s3 / Aws / S3 / S3ClientInterface.php

S3ClientInterface.php in Media Cloud Sync 1.2.0, at includes/sdk/s3/Aws/S3/S3ClientInterface.php

295 lines 13.8 KB

Raw Download Zip

1	<?php
2
3	namespace Dudlewebs\WPMCS\s3\Aws\S3;
4
5	use Dudlewebs\WPMCS\s3\Aws\AwsClientInterface;
6	use Dudlewebs\WPMCS\s3\Aws\CommandInterface;
7	use Dudlewebs\WPMCS\s3\Aws\ResultInterface;
8	use Dudlewebs\WPMCS\s3\Aws\S3\Exception\S3Exception;
9	use Dudlewebs\WPMCS\s3\GuzzleHttp\Promise\PromiseInterface;
10	use Dudlewebs\WPMCS\s3\Psr\Http\Message\RequestInterface;
11	interface S3ClientInterface extends AwsClientInterface
12	{
13	/**
14	* Create a pre-signed URL for the given S3 command object.
15	*
16	* @param CommandInterface $command Command to create a pre-signed
17	* URL for.
18	* @param int\|string\|\DateTimeInterface $expires The time at which the URL should
19	* expire. This can be a Unix
20	* timestamp, a PHP DateTime object,
21	* or a string that can be evaluated
22	* by strtotime().
23	*
24	* @return RequestInterface
25	*/
26	public function createPresignedRequest(CommandInterface $command, $expires, array $options = []);
27	/**
28	* Returns the URL to an object identified by its bucket and key.
29	*
30	* The URL returned by this method is not signed nor does it ensure that the
31	* bucket and key given to the method exist. If you need a signed URL, then
32	* use the {@see \Aws\S3\S3Client::createPresignedRequest} method and get
33	* the URI of the signed request.
34	*
35	* @param string $bucket The name of the bucket where the object is located
36	* @param string $key The key of the object
37	*
38	* @return string The URL to the object
39	*/
40	public function getObjectUrl($bucket, $key);
41	/**
42	* @deprecated Use doesBucketExistV2() instead
43	*
44	* Determines whether or not a bucket exists by name.
45	*
46	* @param string $bucket The name of the bucket
47	*
48	* @return bool
49	*/
50	public function doesBucketExist($bucket);
51	/**
52	* Determines whether or not a bucket exists by name. This method uses S3's
53	* HeadBucket operation and requires the relevant bucket permissions in the
54	* default case to prevent errors.
55	*
56	* @param string $bucket The name of the bucket
57	* @param bool $accept403 Set to true for this method to return true in the case of
58	* invalid bucket-level permissions. Credentials MUST be valid
59	* to avoid inaccuracies. Using the default value of false will
60	* cause an exception to be thrown instead.
61	*
62	* @return bool
63	* @throws S3Exception\|Exception if there is an unhandled exception
64	*/
65	public function doesBucketExistV2($bucket, $accept403);
66	/**
67	* @deprecated Use doesObjectExistV2() instead
68	*
69	* Determines whether or not an object exists by name.
70	*
71	* @param string $bucket The name of the bucket
72	* @param string $key The key of the object
73	* @param array $options Additional options available in the HeadObject
74	* operation (e.g., VersionId).
75	*
76	* @return bool
77	*/
78	public function doesObjectExist($bucket, $key, array $options = []);
79	/**
80	* Determines whether or not an object exists by name. This method uses S3's HeadObject
81	* operation and requires the relevant bucket and object permissions to prevent errors.
82	*
83	* @param string $bucket The name of the bucket
84	* @param string $key The key of the object
85	* @param bool $includeDeleteMarkers Set to true to consider delete markers
86	* existing objects. Using the default value
87	* of false will ignore delete markers and
88	* return false.
89	* @param array $options Additional options available in the HeadObject
90	* operation (e.g., VersionId).
91	*
92	* @return bool
93	* @throws S3Exception\|Exception if there is an unhandled exception
94	*/
95	public function doesObjectExistV2($bucket, $key, $includeDeleteMarkers, array $options = []);
96	/**
97	* Register the Amazon S3 stream wrapper with this client instance.
98	*/
99	public function registerStreamWrapper();
100	/**
101	* Registers the Amazon S3 stream wrapper with this client instance.
102	*
103	*This version uses doesObjectExistV2 and doesBucketExistV2 to check
104	* resource existence.
105	*/
106	public function registerStreamWrapperV2();
107	/**
108	* Deletes objects from Amazon S3 that match the result of a ListObjects
109	* operation. For example, this allows you to do things like delete all
110	* objects that match a specific key prefix.
111	*
112	* @param string $bucket Bucket that contains the object keys
113	* @param string $prefix Optionally delete only objects under this key prefix
114	* @param string $regex Delete only objects that match this regex
115	* @param array $options Aws\S3\BatchDelete options array.
116	*
117	* @see Aws\S3\S3Client::listObjects
118	* @throws \RuntimeException if no prefix and no regex is given
119	*/
120	public function deleteMatchingObjects($bucket, $prefix = '', $regex = '', array $options = []);
121	/**
122	* Deletes objects from Amazon S3 that match the result of a ListObjects
123	* operation. For example, this allows you to do things like delete all
124	* objects that match a specific key prefix.
125	*
126	* @param string $bucket Bucket that contains the object keys
127	* @param string $prefix Optionally delete only objects under this key prefix
128	* @param string $regex Delete only objects that match this regex
129	* @param array $options Aws\S3\BatchDelete options array.
130	*
131	* @see Aws\S3\S3Client::listObjects
132	*
133	* @return PromiseInterface A promise that is settled when matching
134	* objects are deleted.
135	*/
136	public function deleteMatchingObjectsAsync($bucket, $prefix = '', $regex = '', array $options = []);
137	/**
138	* Upload a file, stream, or string to a bucket.
139	*
140	* If the upload size exceeds the specified threshold, the upload will be
141	* performed using concurrent multipart uploads.
142	*
143	* The options array accepts the following options:
144	*
145	* - before_upload: (callable) Callback to invoke before any upload
146	* operations during the upload process. The callback should have a
147	* function signature like `function (Aws\Command $command) {...}`.
148	* - concurrency: (int, default=int(3)) Maximum number of concurrent
149	* `UploadPart` operations allowed during a multipart upload.
150	* - mup_threshold: (int, default=int(16777216)) The size, in bytes, allowed
151	* before the upload must be sent via a multipart upload. Default: 16 MB.
152	* - params: (array, default=array([])) Custom parameters to use with the
153	* upload. For single uploads, they must correspond to those used for the
154	* `PutObject` operation. For multipart uploads, they correspond to the
155	* parameters of the `CreateMultipartUpload` operation.
156	* - part_size: (int) Part size to use when doing a multipart upload.
157	*
158	* @param string $bucket Bucket to upload the object.
159	* @param string $key Key of the object.
160	* @param mixed $body Object data to upload. Can be a
161	* StreamInterface, PHP stream resource, or a
162	* string of data to upload.
163	* @param string $acl ACL to apply to the object (default: private).
164	* @param array $options Options used to configure the upload process.
165	*
166	* @see Aws\S3\MultipartUploader for more info about multipart uploads.
167	* @return ResultInterface Returns the result of the upload.
168	*/
169	public function upload($bucket, $key, $body, $acl = 'private', array $options = []);
170	/**
171	* Upload a file, stream, or string to a bucket asynchronously.
172	*
173	* @param string $bucket Bucket to upload the object.
174	* @param string $key Key of the object.
175	* @param mixed $body Object data to upload. Can be a
176	* StreamInterface, PHP stream resource, or a
177	* string of data to upload.
178	* @param string $acl ACL to apply to the object (default: private).
179	* @param array $options Options used to configure the upload process.
180	*
181	* @see self::upload
182	* @return PromiseInterface Returns a promise that will be fulfilled
183	* with the result of the upload.
184	*/
185	public function uploadAsync($bucket, $key, $body, $acl = 'private', array $options = []);
186	/**
187	* Copy an object of any size to a different location.
188	*
189	* If the upload size exceeds the maximum allowable size for direct S3
190	* copying, a multipart copy will be used.
191	*
192	* The options array accepts the following options:
193	*
194	* - before_upload: (callable) Callback to invoke before any upload
195	* operations during the upload process. The callback should have a
196	* function signature like `function (Aws\Command $command) {...}`.
197	* - concurrency: (int, default=int(5)) Maximum number of concurrent
198	* `UploadPart` operations allowed during a multipart upload.
199	* - params: (array, default=array([])) Custom parameters to use with the
200	* upload. For single uploads, they must correspond to those used for the
201	* `CopyObject` operation. For multipart uploads, they correspond to the
202	* parameters of the `CreateMultipartUpload` operation.
203	* - part_size: (int) Part size to use when doing a multipart upload.
204	*
205	* @param string $fromBucket Bucket where the copy source resides.
206	* @param string $fromKey Key of the copy source.
207	* @param string $destBucket Bucket to which to copy the object.
208	* @param string $destKey Key to which to copy the object.
209	* @param string $acl ACL to apply to the copy (default: private).
210	* @param array $options Options used to configure the upload process.
211	*
212	* @see Aws\S3\MultipartCopy for more info about multipart uploads.
213	* @return ResultInterface Returns the result of the copy.
214	*/
215	public function copy($fromBucket, $fromKey, $destBucket, $destKey, $acl = 'private', array $options = []);
216	/**
217	* Copy an object of any size to a different location asynchronously.
218	*
219	* @param string $fromBucket Bucket where the copy source resides.
220	* @param string $fromKey Key of the copy source.
221	* @param string $destBucket Bucket to which to copy the object.
222	* @param string $destKey Key to which to copy the object.
223	* @param string $acl ACL to apply to the copy (default: private).
224	* @param array $options Options used to configure the upload process.
225	*
226	* @see self::copy for more info about the parameters above.
227	* @return PromiseInterface Returns a promise that will be fulfilled
228	* with the result of the copy.
229	*/
230	public function copyAsync($fromBucket, $fromKey, $destBucket, $destKey, $acl = 'private', array $options = []);
231	/**
232	* Recursively uploads all files in a given directory to a given bucket.
233	*
234	* @param string $directory Full path to a directory to upload
235	* @param string $bucket Name of the bucket
236	* @param string $keyPrefix Virtual directory key prefix to add to each upload
237	* @param array $options Options available in Aws\S3\Transfer::__construct
238	*
239	* @see Aws\S3\Transfer for more options and customization
240	*/
241	public function uploadDirectory($directory, $bucket, $keyPrefix = null, array $options = []);
242	/**
243	* Recursively uploads all files in a given directory to a given bucket.
244	*
245	* @param string $directory Full path to a directory to upload
246	* @param string $bucket Name of the bucket
247	* @param string $keyPrefix Virtual directory key prefix to add to each upload
248	* @param array $options Options available in Aws\S3\Transfer::__construct
249	*
250	* @see Aws\S3\Transfer for more options and customization
251	*
252	* @return PromiseInterface A promise that is settled when the upload is
253	* complete.
254	*/
255	public function uploadDirectoryAsync($directory, $bucket, $keyPrefix = null, array $options = []);
256	/**
257	* Downloads a bucket to the local filesystem
258	*
259	* @param string $directory Directory to download to
260	* @param string $bucket Bucket to download from
261	* @param string $keyPrefix Only download objects that use this key prefix
262	* @param array $options Options available in Aws\S3\Transfer::__construct
263	*/
264	public function downloadBucket($directory, $bucket, $keyPrefix = '', array $options = []);
265	/**
266	* Downloads a bucket to the local filesystem
267	*
268	* @param string $directory Directory to download to
269	* @param string $bucket Bucket to download from
270	* @param string $keyPrefix Only download objects that use this key prefix
271	* @param array $options Options available in Aws\S3\Transfer::__construct
272	*
273	* @return PromiseInterface A promise that is settled when the download is
274	* complete.
275	*/
276	public function downloadBucketAsync($directory, $bucket, $keyPrefix = '', array $options = []);
277	/**
278	* Returns the region in which a given bucket is located.
279	*
280	* @param string $bucketName
281	*
282	* @return string
283	*/
284	public function determineBucketRegion($bucketName);
285	/**
286	* Returns a promise fulfilled with the region in which a given bucket is
287	* located.
288	*
289	* @param string $bucketName
290	*
291	* @return PromiseInterface
292	*/
293	public function determineBucketRegionAsync($bucketName);
294	}
295