Cloud Storage Client - Class StorageClient (1.42.0)

Reference documentation and code samples for the Cloud Storage Client class StorageClient.

Google Cloud Storage allows you to store and retrieve data on Google's infrastructure. Find more information at the Google Cloud Storage API docs.

Example:

use Google\Cloud\Storage\StorageClient;

$storage = new StorageClient();

Namespace

Google \ Cloud \ Storage

Methods

__construct

Create a Storage client.

Parameters
Name Description
config array

Configuration options.

↳ apiEndpoint string

The hostname with optional port to use in place of the default service endpoint. Example: foobar.com or foobar.com:1234.

↳ projectId string

The project ID from the Google Developer's Console.

↳ authCache CacheItemPoolInterface

A cache used storing access tokens. Defaults to a simple in memory implementation.

↳ authCacheOptions array

Cache configuration options.

↳ authHttpHandler callable

A handler used to deliver Psr7 requests specifically for authentication.

↳ credentialsFetcher FetchAuthTokenInterface

A credentials fetcher instance.

↳ httpHandler callable

A handler used to deliver Psr7 requests. Only valid for requests sent over REST.

↳ keyFile array

The contents of the service account credentials .json file retrieved from the Google Developer's Console. Ex: json_decode(file_get_contents($path), true).

↳ keyFilePath string

The full path to your service account credentials .json file retrieved from the Google Developers Console.

↳ requestTimeout float

Seconds to wait before timing out the request. Defaults to 0 with REST and 60 with gRPC.

↳ retries int

Number of retries for a failed request. Defaults to 3.

↳ scopes array

Scopes to be used for the request.

↳ quotaProject string

Specifies a user project to bill for access charges associated with the request.

bucket

Lazily instantiates a bucket.

There are no network requests made at this point. To see the operations that can be performed on a bucket please see Google\Cloud\Storage\Bucket.

If $userProject is set to true, the current project ID (used to instantiate the client) will be billed for all requests. If $userProject is a project ID, given as a string, that project will be billed for all requests. This only has an effect when the bucket is not owned by the current or given project ID.

Example:

$bucket = $storage->bucket('my-bucket');
Parameters
Name Description
name string

The name of the bucket to request.

userProject string|bool

If true, the current Project ID will be used. If a string, that string will be used as the userProject argument, and that project will be billed for the request. Defaults to false.

Returns
Type Description
Google\Cloud\Storage\Bucket

buckets

Parameters
Name Description
options array

Configuration options.

↳ maxResults int

Maximum number of results to return per requested page.

↳ resultLimit int

Limit the number of results returned in total. Defaults to 0 (return all results).

↳ pageToken string

A previously-returned page token used to resume the loading of results from a specific point.

↳ prefix string

Filter results with this prefix.

↳ projection string

Determines which properties to return. May be either 'full' or 'noAcl'.

↳ fields string

Selector which will cause the response to only return the specified fields.

↳ userProject string

If set, this is the ID of the project which will be billed for the request.

↳ bucketUserProject bool

If true, each returned instance will have $userProject set to the value of $options.userProject. If false, $options.userProject will be used ONLY for the listBuckets operation. If $options.userProject is not set, this option has no effect. Defaults to true.

Returns
Type Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\storage\bucket>

createBucket

Parameters
Name Description
name string

Name of the bucket to be created.

options array

Configuration options.

↳ predefinedAcl string

Predefined ACL to apply to the bucket. Acceptable values include, "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", and "publicRead".

↳ predefinedDefaultObjectAcl string

Apply a predefined set of default object access controls to this bucket.

↳ enableObjectRetention bool

Whether object retention should be enabled on this bucket. For more information, refer to the Object Retention Lock documentation.

↳ projection string

Determines which properties to return. May be either "full" or "noAcl". Defaults to "noAcl", unless the bucket resource specifies acl or defaultObjectAcl properties, when it defaults to "full".

↳ fields string

Selector which will cause the response to only return the specified fields.

↳ acl array

Access controls on the bucket.

↳ cors array

The bucket's Cross-Origin Resource Sharing (CORS) configuration.

↳ defaultObjectAcl array

Default access controls to apply to new objects when no ACL is provided.

↳ lifecycle array|Lifecycle

The bucket's lifecycle configuration.

↳ location string

The location of the bucket. If specifying a dual-region, the customPlacementConfig property should be set in conjunction. For more information, see Bucket Locations. Defaults to "US".

↳ hierarchicalNamespace array

The hierarchical namespace configuration on this bucket.

↳ customPlacementConfig array

The bucket's dual regions. For more information, see Bucket Locations.

↳ logging array

The bucket's logging configuration, which defines the destination bucket and optional name prefix for the current bucket's logs.

↳ storageClass string

The bucket's storage class. This defines how objects in the bucket are stored and determines the SLA and the cost of storage. Acceptable values include the following strings: "STANDARD", "NEARLINE", "COLDLINE" and "ARCHIVE". Legacy values including "MULTI_REGIONAL", "REGIONAL" and "DURABLE_REDUCED_AVAILABILITY" are also available, but should be avoided for new implementations. For more information, refer to the Storage Classes documentation. Defaults to "STANDARD".

↳ autoclass array

The bucket's autoclass configuration. Buckets can have either StorageClass OLM rules or Autoclass, but not both. When Autoclass is enabled on a bucket, adding StorageClass OLM rules will result in failure. For more information, refer to Storage Autoclass

↳ versioning array

The bucket's versioning configuration.

↳ website array

The bucket's website configuration.

↳ billing array

The bucket's billing configuration.

↳ billing bool

.requesterPays When true, requests to this bucket and objects within it must provide a project ID to which the request will be billed.

↳ labels array

The Bucket labels. Labels are represented as an array of keys and values. To remove an existing label, set its value to null.

↳ userProject string

If set, this is the ID of the project which will be billed for the request.

↳ bucketUserProject bool

If true, the returned instance will have $userProject set to the value of $options.userProject. If false, $options.userProject will be used ONLY for the createBucket operation. If $options.userProject is not set, this option has no effect. Defaults to true.

↳ encryption array

Encryption configuration used by default for newly inserted objects.

↳ encryption string

.defaultKmsKeyName A Cloud KMS Key used to encrypt objects uploaded into this bucket. Should be in the format projects/my-project/locations/kr-location/keyRings/my-kr/cryptoKeys/my-key. Please note the KMS key ring must use the same location as the bucket.

↳ defaultEventBasedHold bool

When true, newly created objects in this bucket will be retained indefinitely until an event occurs, signified by the hold's release.

↳ retentionPolicy array

Defines the retention policy for a bucket. In order to lock a retention policy, please see Google\Cloud\Storage\Bucket::lockRetentionPolicy().

↳ retentionPolicy int

.retentionPeriod Specifies the retention period for objects in seconds. During the retention period an object cannot be overwritten or deleted. Retention period must be greater than zero and less than 100 years.

↳ iamConfiguration array

The bucket's IAM configuration.

↳ iamConfiguration bool

.bucketPolicyOnly.enabled this is an alias for $iamConfiguration.uniformBucketLevelAccess.

↳ iamConfiguration bool

.uniformBucketLevelAccess.enabled If set and true, access checks only use bucket-level IAM policies or above. When enabled, requests attempting to view or manipulate ACLs will fail with error code 400. NOTE: Before using Uniform bucket-level access, please review the feature documentation, as well as Should You Use uniform bucket-level access

↳ rpo string

Specifies the Turbo Replication setting for a dual-region bucket. The possible values are DEFAULT and ASYNC_TURBO. Trying to set the rpo for a non dual-region bucket will throw an exception. Non existence of this parameter is equivalent to it being DEFAULT.

Returns
Type Description
Google\Cloud\Storage\Bucket

registerStreamWrapper

Registers this StorageClient as the handler for stream reading/writing.

Parameter
Name Description
protocol string

The name of the protocol to use. Defaults to gs.

unregisterStreamWrapper

Unregisters the SteamWrapper

Parameter
Name Description
protocol string

The name of the protocol to unregister. Defaults to gs.

signedUrlUploader

Create an uploader to handle a Signed URL.

Example:

$uploader = $storage->signedUrlUploader($uri, fopen('/path/to/myfile.doc', 'r'));
Parameters
Name Description
uri string

The URI to accept an upload request.

data string|resource|Psr\Http\Message\StreamInterface

The data to be uploaded

options array

[optional] Configuration Options. Refer to Google\Cloud\Core\Upload\AbstractUploader::__construct().

Returns
Type Description
Google\Cloud\Core\Upload\SignedUrlUploader

timestamp

Create a Timestamp object.

Example:

$timestamp = $storage->timestamp(new \DateTime('2003-02-05 11:15:02.421827Z'));
Parameters
Name Description
timestamp DateTimeInterface

The timestamp value.

nanoSeconds int

[optional] The number of nanoseconds in the timestamp.

Returns
Type Description
Google\Cloud\Core\Timestamp

getServiceAccount

Get the service account email associated with this client.

Example:

$serviceAccount = $storage->getServiceAccount();
Parameters
Name Description
options array

Configuration options.

↳ userProject string

If set, this is the ID of the project which will be billed for the request.

Returns
Type Description
string

hmacKeys

List Service Account HMAC keys in the project.

Example:

$hmacKeys = $storage->hmacKeys();
// Get the HMAC keys associated with a Service Account email
$hmacKeys = $storage->hmacKeys([
    'serviceAccountEmail' => $serviceAccountEmail
]);
Parameters
Name Description
options array

Configuration Options

↳ serviceAccountEmail string

If present, only keys for the given service account are returned.

↳ showDeletedKeys bool

Whether or not to show keys in the DELETED state.

↳ userProject string

If set, this is the ID of the project which will be billed for the request.

↳ projectId string

The project ID to use, if different from that with which the client was created.

Returns
Type Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\storage\hmackey>

hmacKey

Lazily instantiate an HMAC Key instance using an Access ID.

Example:

$hmacKey = $storage->hmacKey($accessId);
Parameters
Name Description
accessId string

The ID of the HMAC Key.

projectId string

[optional] The project ID to use, if different from that with which the client was created.

metadata array

[optional] HMAC key metadata.

Returns
Type Description
Google\Cloud\Storage\HmacKey

createHmacKey

Creates a new HMAC key for the specified service account.

Please note that the HMAC secret is only available at creation. Make sure to note the secret after creation.

Example:

$response = $storage->createHmacKey('account@myProject.iam.gserviceaccount.com');
$secret = $response->secret();
Parameters
Name Description
serviceAccountEmail string

Email address of the service account.

options array

Configuration Options

↳ userProject string

If set, this is the ID of the project which will be billed for the request. NOTE: This option is currently ignored by Cloud Storage.

↳ projectId string

The project ID to use, if different from that with which the client was created.

Returns
Type Description
Google\Cloud\Storage\CreatedHmacKey

Constants

VERSION

Value: '1.42.0'

FULL_CONTROL_SCOPE

Value: 'https://www.googleapis.com/auth/devstorage.full_control'

READ_ONLY_SCOPE

Value: 'https://www.googleapis.com/auth/devstorage.read_only'

READ_WRITE_SCOPE

Value: 'https://www.googleapis.com/auth/devstorage.read_write'

RETRY_NEVER

Value: 'never'

Retry strategy to signify that we never want to retry an operation even if the error is retryable.

We can set $options['retryStrategy'] to one of "always", "never" and "idempotent".

RETRY_ALWAYS

Value: 'always'

Retry strategy to signify that we always want to retry an operation.

RETRY_IDEMPOTENT

Value: 'idempotent'

This is the default. This signifies that we want to retry an operation only if it is retryable and the error is retryable.