media-cloud-sync / includes / sdk / google / google / cloud-storage / src / StorageClient.php

StorageClient.php in Media Cloud Sync 1.1.1, at includes/sdk/google/google/cloud-storage/src/StorageClient.php

529 lines 23.9 KB

Raw Download Zip

1	<?php
2
3	/**
4	* Copyright 2015 Google Inc. All Rights Reserved.
5	*
6	* Licensed under the Apache License, Version 2.0 (the "License");
7	* you may not use this file except in compliance with the License.
8	* You may obtain a copy of the License at
9	*
10	* http://www.apache.org/licenses/LICENSE-2.0
11	*
12	* Unless required by applicable law or agreed to in writing, software
13	* distributed under the License is distributed on an "AS IS" BASIS,
14	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15	* See the License for the specific language governing permissions and
16	* limitations under the License.
17	*/
18	namespace Dudlewebs\WPMCS\Google\Cloud\Storage;
19
20	use Dudlewebs\WPMCS\Google\Auth\FetchAuthTokenInterface;
21	use Dudlewebs\WPMCS\Google\Cloud\Core\ArrayTrait;
22	use Dudlewebs\WPMCS\Google\Cloud\Core\ClientTrait;
23	use Dudlewebs\WPMCS\Google\Cloud\Core\Exception\GoogleException;
24	use Dudlewebs\WPMCS\Google\Cloud\Core\Iterator\ItemIterator;
25	use Dudlewebs\WPMCS\Google\Cloud\Core\Iterator\PageIterator;
26	use Dudlewebs\WPMCS\Google\Cloud\Core\Timestamp;
27	use Dudlewebs\WPMCS\Google\Cloud\Core\Upload\SignedUrlUploader;
28	use Dudlewebs\WPMCS\Google\Cloud\Storage\Connection\ConnectionInterface;
29	use Dudlewebs\WPMCS\Google\Cloud\Storage\Connection\Rest;
30	use Dudlewebs\WPMCS\Psr\Cache\CacheItemPoolInterface;
31	use Dudlewebs\WPMCS\Psr\Http\Message\StreamInterface;
32	/**
33	* Google Cloud Storage allows you to store and retrieve data on Google's
34	* infrastructure. Find more information at the
35	* [Google Cloud Storage API docs](https://developers.google.com/storage).
36	*
37	* Example:
38	* ```
39	* use Google\Cloud\Storage\StorageClient;
40	*
41	* $storage = new StorageClient();
42	* ```
43	*/
44	class StorageClient
45	{
46	use ArrayTrait;
47	use ClientTrait;
48	const VERSION = '1.39.0';
49	const FULL_CONTROL_SCOPE = 'https://www.googleapis.com/auth/devstorage.full_control';
50	const READ_ONLY_SCOPE = 'https://www.googleapis.com/auth/devstorage.read_only';
51	const READ_WRITE_SCOPE = 'https://www.googleapis.com/auth/devstorage.read_write';
52	/**
53	* Retry strategy to signify that we never want to retry an operation
54	* even if the error is retryable.
55	*
56	* We can set $options['retryStrategy'] to one of "always", "never" and
57	* "idempotent".
58	*/
59	const RETRY_NEVER = 'never';
60	/**
61	* Retry strategy to signify that we always want to retry an operation.
62	*/
63	const RETRY_ALWAYS = 'always';
64	/**
65	* This is the default. This signifies that we want to retry an operation
66	* only if it is retryable and the error is retryable.
67	*/
68	const RETRY_IDEMPOTENT = 'idempotent';
69	/**
70	* @var ConnectionInterface Represents a connection to Storage.
71	* @internal
72	*/
73	protected $connection;
74	/**
75	* Create a Storage client.
76	*
77	* @param array $config [optional] {
78	* Configuration options.
79	*
80	* @type string $apiEndpoint The hostname with optional port to use in
81	* place of the default service endpoint. Example:
82	* `foobar.com` or `foobar.com:1234`.
83	* @type string $projectId The project ID from the Google Developer's
84	* Console.
85	* @type CacheItemPoolInterface $authCache A cache used storing access
86	* tokens. Defaults to a simple in memory implementation.
87	* @type array $authCacheOptions Cache configuration options.
88	* @type callable $authHttpHandler A handler used to deliver Psr7
89	* requests specifically for authentication.
90	* @type FetchAuthTokenInterface $credentialsFetcher A credentials
91	* fetcher instance.
92	* @type callable $httpHandler A handler used to deliver Psr7 requests.
93	* Only valid for requests sent over REST.
94	* @type array $keyFile The contents of the service account credentials
95	* .json file retrieved from the Google Developer's Console.
96	* Ex: `json_decode(file_get_contents($path), true)`.
97	* @type string $keyFilePath The full path to your service account
98	* credentials .json file retrieved from the Google Developers
99	* Console.
100	* @type float $requestTimeout Seconds to wait before timing out the
101	* request. Defaults to `0` with REST and `60` with gRPC.
102	* @type int $retries Number of retries for a failed request.
103	* Defaults to `3`.
104	* @type array $scopes Scopes to be used for the request.
105	* @type string $quotaProject Specifies a user project to bill for
106	* access charges associated with the request.
107	* }
108	*/
109	public function __construct(array $config = [])
110	{
111	if (!isset($config['scopes'])) {
112	$config['scopes'] = ['https://www.googleapis.com/auth/iam', self::FULL_CONTROL_SCOPE];
113	}
114	$this->connection = new Rest($this->configureAuthentication($config) + ['projectId' => $this->projectId]);
115	}
116	/**
117	* Lazily instantiates a bucket.
118	*
119	* There are no network requests made at this point. To see the operations
120	* that can be performed on a bucket please see {@see Bucket}.
121	*
122	* If `$userProject` is set to true, the current project ID (used to
123	* instantiate the client) will be billed for all requests. If
124	* `$userProject` is a project ID, given as a string, that project
125	* will be billed for all requests. This only has an effect when the bucket
126	* is not owned by the current or given project ID.
127	*
128	* Example:
129	* ```
130	* $bucket = $storage->bucket('my-bucket');
131	* ```
132	*
133	* @param string $name The name of the bucket to request.
134	* @param string\|bool $userProject If true, the current Project ID
135	* will be used. If a string, that string will be used as the
136	* userProject argument, and that project will be billed for the
137	* request. Defaults to `false`.
138	* @return Bucket
139	*/
140	public function bucket($name, $userProject = \false)
141	{
142	if (!$userProject) {
143	$userProject = null;
144	} elseif (!is_string($userProject)) {
145	$userProject = $this->projectId;
146	}
147	return new Bucket($this->connection, $name, ['requesterProjectId' => $userProject]);
148	}
149	/**
150	* Fetches all buckets in the project.
151	*
152	* Example:
153	* ```
154	* $buckets = $storage->buckets();
155	* ```
156	*
157	* ```
158	* // Get all buckets beginning with the prefix 'album'.
159	* $buckets = $storage->buckets([
160	* 'prefix' => 'album'
161	* ]);
162	*
163	* foreach ($buckets as $bucket) {
164	* echo $bucket->name() . PHP_EOL;
165	* }
166	* ```
167	*
168	* @see https://cloud.google.com/storage/docs/json_api/v1/buckets/list Buckets list API documentation.
169	*
170	* @param array $options [optional] {
171	* Configuration options.
172	*
173	* @type int $maxResults Maximum number of results to return per
174	* requested page.
175	* @type int $resultLimit Limit the number of results returned in total.
176	* Defaults to `0` (return all results).
177	* @type string $pageToken A previously-returned page token used to
178	* resume the loading of results from a specific point.
179	* @type string $prefix Filter results with this prefix.
180	* @type string $projection Determines which properties to return. May
181	* be either 'full' or 'noAcl'.
182	* @type string $fields Selector which will cause the response to only
183	* return the specified fields.
184	* @type string $userProject If set, this is the ID of the project which
185	* will be billed for the request.
186	* @type bool $bucketUserProject If true, each returned instance will
187	* have `$userProject` set to the value of `$options.userProject`.
188	* If false, `$options.userProject` will be used ONLY for the
189	* listBuckets operation. If `$options.userProject` is not set,
190	* this option has no effect. Defaults to `true`.
191	* }
192	* @return ItemIterator<Bucket>
193	* @throws GoogleException When a project ID has not been detected.
194	*/
195	public function buckets(array $options = [])
196	{
197	$this->requireProjectId();
198	$resultLimit = $this->pluck('resultLimit', $options, \false);
199	$bucketUserProject = $this->pluck('bucketUserProject', $options, \false);
200	$bucketUserProject = !is_null($bucketUserProject) ? $bucketUserProject : \true;
201	$userProject = isset($options['userProject']) && $bucketUserProject ? $options['userProject'] : null;
202	return new ItemIterator(new PageIterator(function (array $bucket) use ($userProject) {
203	return new Bucket($this->connection, $bucket['name'], $bucket + ['requesterProjectId' => $userProject]);
204	}, [$this->connection, 'listBuckets'], $options + ['project' => $this->projectId], ['resultLimit' => $resultLimit]));
205	}
206	/**
207	* Create a bucket. Bucket names must be unique as Cloud Storage uses a flat
208	* namespace. For more information please see
209	* [bucket name requirements](https://cloud.google.com/storage/docs/naming#requirements)
210	*
211	* Example:
212	* ```
213	* $bucket = $storage->createBucket('bucket');
214	* ```
215	*
216	* ```
217	* // Create a bucket with logging enabled.
218	* $bucket = $storage->createBucket('myBeautifulBucket', [
219	* 'logging' => [
220	* 'logBucket' => 'bucketToLogTo',
221	* 'logObjectPrefix' => 'myPrefix'
222	* ]
223	* ]);
224	* ```
225	*
226	* @see https://cloud.google.com/storage/docs/json_api/v1/buckets/insert Buckets insert API documentation.
227	*
228	* @param string $name Name of the bucket to be created.
229	* @codingStandardsIgnoreStart
230	* @param array $options [optional] {
231	* Configuration options.
232	*
233	* @type string $predefinedAcl Predefined ACL to apply to the bucket.
234	* Acceptable values include, `"authenticatedRead"`,
235	* `"bucketOwnerFullControl"`, `"bucketOwnerRead"`, `"private"`,
236	* `"projectPrivate"`, and `"publicRead"`.
237	* @type string $predefinedDefaultObjectAcl Apply a predefined set of
238	* default object access controls to this bucket.
239	* @type bool $enableObjectRetention Whether object retention should
240	* be enabled on this bucket. For more information, refer to the
241	* [Object Retention Lock](https://cloud.google.com/storage/docs/object-lock)
242	* documentation.
243	* @type string $projection Determines which properties to return. May
244	* be either `"full"` or `"noAcl"`. Defaults to `"noAcl"`,
245	* unless the bucket resource specifies acl or defaultObjectAcl
246	* properties, when it defaults to `"full"`.
247	* @type string $fields Selector which will cause the response to only
248	* return the specified fields.
249	* @type array $acl Access controls on the bucket.
250	* @type array $cors The bucket's Cross-Origin Resource Sharing (CORS)
251	* configuration.
252	* @type array $defaultObjectAcl Default access controls to apply to new
253	* objects when no ACL is provided.
254	* @type array\|Lifecycle $lifecycle The bucket's lifecycle configuration.
255	* @type string $location The location of the bucket. If specifying
256	* a dual-region, the `customPlacementConfig` property should be
257	* set in conjunction. For more information, see
258	* [Bucket Locations](https://cloud.google.com/storage/docs/locations).
259	* Defaults to `"US"`.
260	* @type array $customPlacementConfig The bucket's dual regions. For more
261	* information, see
262	* [Bucket Locations](https://cloud.google.com/storage/docs/locations).
263	* @type array $logging The bucket's logging configuration, which
264	* defines the destination bucket and optional name prefix for the
265	* current bucket's logs.
266	* @type string $storageClass The bucket's storage class. This defines
267	* how objects in the bucket are stored and determines the SLA and
268	* the cost of storage. Acceptable values include the following
269	* strings: `"STANDARD"`, `"NEARLINE"`, `"COLDLINE"` and
270	* `"ARCHIVE"`. Legacy values including `"MULTI_REGIONAL"`,
271	* `"REGIONAL"` and `"DURABLE_REDUCED_AVAILABILITY"` are also
272	* available, but should be avoided for new implementations. For
273	* more information, refer to the
274	* [Storage Classes](https://cloud.google.com/storage/docs/storage-classes)
275	* documentation. Defaults to `"STANDARD"`.
276	* @type array $autoclass The bucket's autoclass configuration.
277	* Buckets can have either StorageClass OLM rules or Autoclass,
278	* but not both. When Autoclass is enabled on a bucket, adding
279	* StorageClass OLM rules will result in failure.
280	* For more information, refer to
281	* [Storage Autoclass](https://cloud.google.com/storage/docs/autoclass)
282	* @type array $versioning The bucket's versioning configuration.
283	* @type array $website The bucket's website configuration.
284	* @type array $billing The bucket's billing configuration.
285	* @type bool $billing.requesterPays When `true`, requests to this bucket
286	* and objects within it must provide a project ID to which the
287	* request will be billed.
288	* @type array $labels The Bucket labels. Labels are represented as an
289	* array of keys and values. To remove an existing label, set its
290	* value to `null`.
291	* @type string $userProject If set, this is the ID of the project which
292	* will be billed for the request.
293	* @type bool $bucketUserProject If true, the returned instance will
294	* have `$userProject` set to the value of `$options.userProject`.
295	* If false, `$options.userProject` will be used ONLY for the
296	* createBucket operation. If `$options.userProject` is not set,
297	* this option has no effect. Defaults to `true`.
298	* @type array $encryption Encryption configuration used by default for
299	* newly inserted objects.
300	* @type string $encryption.defaultKmsKeyName A Cloud KMS Key used to
301	* encrypt objects uploaded into this bucket. Should be in the
302	* format
303	* `projects/my-project/locations/kr-location/keyRings/my-kr/cryptoKeys/my-key`.
304	* Please note the KMS key ring must use the same location as the
305	* bucket.
306	* @type bool $defaultEventBasedHold When `true`, newly created objects
307	* in this bucket will be retained indefinitely until an event
308	* occurs, signified by the hold's release.
309	* @type array $retentionPolicy Defines the retention policy for a
310	* bucket. In order to lock a retention policy, please see
311	* {@see Bucket::lockRetentionPolicy()}.
312	* @type int $retentionPolicy.retentionPeriod Specifies the retention
313	* period for objects in seconds. During the retention period an
314	* object cannot be overwritten or deleted. Retention period must
315	* be greater than zero and less than 100 years.
316	* @type array $iamConfiguration The bucket's IAM configuration.
317	* @type bool $iamConfiguration.bucketPolicyOnly.enabled this is an alias
318	* for $iamConfiguration.uniformBucketLevelAccess.
319	* @type bool $iamConfiguration.uniformBucketLevelAccess.enabled If set and
320	* true, access checks only use bucket-level IAM policies or
321	* above. When enabled, requests attempting to view or manipulate
322	* ACLs will fail with error code 400. NOTE: Before using
323	* Uniform bucket-level access, please review the
324	* [feature documentation](https://cloud.google.com/storage/docs/uniform-bucket-level-access),
325	* as well as
326	* [Should You Use uniform bucket-level access](https://cloud.google.com/storage/docs/uniform-bucket-level-access#should-you-use)
327	* @type string $rpo Specifies the Turbo Replication setting for a dual-region bucket.
328	* The possible values are DEFAULT and ASYNC_TURBO. Trying to set the rpo for a non dual-region
329	* bucket will throw an exception. Non existence of this parameter is equivalent to it being DEFAULT.
330	* }
331	* @codingStandardsIgnoreEnd
332	* @return Bucket
333	* @throws GoogleException When a project ID has not been detected.
334	*/
335	public function createBucket($name, array $options = [])
336	{
337	$this->requireProjectId();
338	if (isset($options['lifecycle']) && $options['lifecycle'] instanceof Lifecycle) {
339	$options['lifecycle'] = $options['lifecycle']->toArray();
340	}
341	$bucketUserProject = $this->pluck('bucketUserProject', $options, \false);
342	$bucketUserProject = !is_null($bucketUserProject) ? $bucketUserProject : \true;
343	$userProject = isset($options['userProject']) && $bucketUserProject ? $options['userProject'] : null;
344	$response = $this->connection->insertBucket($options + ['name' => $name, 'project' => $this->projectId]);
345	return new Bucket($this->connection, $name, $response + ['requesterProjectId' => $userProject]);
346	}
347	/**
348	* Registers this StorageClient as the handler for stream reading/writing.
349	*
350	* @param string $protocol The name of the protocol to use. Defaults to `gs`.
351	* @throws \RuntimeException
352	*/
353	public function registerStreamWrapper($protocol = null)
354	{
355	return StreamWrapper::register($this, $protocol);
356	}
357	/**
358	* Unregisters the SteamWrapper
359	*
360	* @param string $protocol The name of the protocol to unregister. Defaults to `gs`.
361	*/
362	public function unregisterStreamWrapper($protocol = null)
363	{
364	StreamWrapper::unregister($protocol);
365	}
366	/**
367	* Create an uploader to handle a Signed URL.
368	*
369	* Example:
370	* ```
371	* $uploader = $storage->signedUrlUploader($uri, fopen('/path/to/myfile.doc', 'r'));
372	* ```
373	*
374	* @param string $uri The URI to accept an upload request.
375	* @param string\|resource\|StreamInterface $data The data to be uploaded
376	* @param array $options [optional] Configuration Options. Refer to
377	* {@see \Google\Cloud\Core\Upload\AbstractUploader::__construct()}.
378	* @return SignedUrlUploader
379	*/
380	public function signedUrlUploader($uri, $data, array $options = [])
381	{
382	return new SignedUrlUploader($this->connection->requestWrapper(), $data, $uri, $options);
383	}
384	/**
385	* Create a Timestamp object.
386	*
387	* Example:
388	* ```
389	* $timestamp = $storage->timestamp(new \DateTime('2003-02-05 11:15:02.421827Z'));
390	* ```
391	*
392	* @param \DateTimeInterface $timestamp The timestamp value.
393	* @param int $nanoSeconds [optional] The number of nanoseconds in the timestamp.
394	* @return Timestamp
395	*/
396	public function timestamp(\DateTimeInterface $timestamp, $nanoSeconds = null)
397	{
398	return new Timestamp($timestamp, $nanoSeconds);
399	}
400	/**
401	* Get the service account email associated with this client.
402	*
403	* Example:
404	* ```
405	* $serviceAccount = $storage->getServiceAccount();
406	* ```
407	*
408	* @param array $options [optional] {
409	* Configuration options.
410	*
411	* @type string $userProject If set, this is the ID of the project which
412	* will be billed for the request.
413	* }
414	* @return string
415	*/
416	public function getServiceAccount(array $options = [])
417	{
418	$resp = $this->connection->getServiceAccount($options + ['projectId' => $this->projectId]);
419	return $resp['email_address'];
420	}
421	/**
422	* List Service Account HMAC keys in the project.
423	*
424	* Example:
425	* ```
426	* $hmacKeys = $storage->hmacKeys();
427	* ```
428	*
429	* ```
430	* // Get the HMAC keys associated with a Service Account email
431	* $hmacKeys = $storage->hmacKeys([
432	* 'serviceAccountEmail' => $serviceAccountEmail
433	* ]);
434	* ```
435	*
436	* @param array $options {
437	* Configuration Options
438	*
439	* @type string $serviceAccountEmail If present, only keys for the given
440	* service account are returned.
441	* @type bool $showDeletedKeys Whether or not to show keys in the
442	* DELETED state.
443	* @type string $userProject If set, this is the ID of the project which
444	* will be billed for the request.
445	* @type string $projectId The project ID to use, if different from that
446	* with which the client was created.
447	* }
448	* @return ItemIterator<HmacKey>
449	*/
450	public function hmacKeys(array $options = [])
451	{
452	$options += ['projectId' => $this->projectId];
453	if (!$options['projectId']) {
454	$this->requireProjectId();
455	}
456	$resultLimit = $this->pluck('resultLimit', $options, \false);
457	return new ItemIterator(new PageIterator(function (array $metadata) use ($options) {
458	return $this->hmacKey($metadata['accessId'], $options['projectId'], $metadata);
459	}, [$this->connection, 'listHmacKeys'], $options, ['resultLimit' => $resultLimit]));
460	}
461	/**
462	* Lazily instantiate an HMAC Key instance using an Access ID.
463	*
464	* Example:
465	* ```
466	* $hmacKey = $storage->hmacKey($accessId);
467	* ```
468	*
469	* @param string $accessId The ID of the HMAC Key.
470	* @param string $projectId [optional] The project ID to use, if different
471	* from that with which the client was created.
472	* @param array $metadata [optional] HMAC key metadata.
473	* @return HmacKey
474	*/
475	public function hmacKey($accessId, $projectId = null, array $metadata = [])
476	{
477	if (!$projectId) {
478	$this->requireProjectId();
479	}
480	return new HmacKey($this->connection, $projectId ?: $this->projectId, $accessId, $metadata);
481	}
482	/**
483	* Creates a new HMAC key for the specified service account.
484	*
485	* Please note that the HMAC secret is only available at creation. Make sure
486	* to note the secret after creation.
487	*
488	* Example:
489	* ```
490	* $response = $storage->createHmacKey('[email protected]');
491	* $secret = $response->secret();
492	* ```
493	*
494	* @param string $serviceAccountEmail Email address of the service account.
495	* @param array $options {
496	* Configuration Options
497	*
498	* @type string $userProject If set, this is the ID of the project which
499	* will be billed for the request. NOTE: This option is
500	* currently ignored by Cloud Storage.
501	* @type string $projectId The project ID to use, if different from that
502	* with which the client was created.
503	* }
504	* @return CreatedHmacKey
505	*/
506	public function createHmacKey($serviceAccountEmail, array $options = [])
507	{
508	$options += ['projectId' => $this->projectId];
509	if (!$options['projectId']) {
510	$this->requireProjectId();
511	}
512	$res = $this->connection->createHmacKey(['projectId' => $options['projectId'], 'serviceAccountEmail' => $serviceAccountEmail] + $options);
513	$key = new HmacKey($this->connection, $options['projectId'], $res['metadata']['accessId'], $res['metadata']);
514	return new CreatedHmacKey($key, $res['secret']);
515	}
516	/**
517	* Throw an exception if no project ID available.
518	*
519	* @return void
520	* @throws GoogleException
521	*/
522	private function requireProjectId()
523	{
524	if (!$this->projectId) {
525	throw new GoogleException('No project ID was provided, ' . 'and we were unable to detect a default project ID.');
526	}
527	}
528	}
529