Cloud Storage Client - Class StorageObject (1.45.0)

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

Objects are the individual pieces of data that you store in Google Cloud Storage.

Example:

use Google\Cloud\Storage\StorageClient;

$storage = new StorageClient();

$bucket = $storage->bucket('my-bucket');
$object = $bucket->object('my-object');

Namespace

Google \ Cloud \ Storage

Methods

__construct

Parameters
Name Description
connection Connection\ConnectionInterface

Represents a connection to Cloud Storage. This object is created by StorageClient, and should not be instantiated outside of this client.
name string

The object's name.
bucket string

The name of the bucket the object is contained in.
generation string

[optional] The generation of the object.
info array

[optional] The object's metadata.
encryptionKey string

[optional] An AES-256 customer-supplied encryption key.
encryptionKeySHA256 string

[optional] The SHA256 hash of the customer-supplied encryption key.

acl

See also:

Returns
Type Description
Acl

exists

Check whether or not the object exists.

Example:

if ($object->exists()) {
    echo 'Object exists!';
}
Parameter
Name Description
options array

[optional] Configuration options.
Returns
Type Description
bool

delete

See also:

Parameters
Name Description
options array

Configuration options.
↳ ifGenerationMatch string

Makes the operation conditional on whether the object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the object's current metageneration does not match the given value.
Returns
Type Description
void

update

See also:

Parameters
Name Description
metadata array

The available options for metadata are outlined at the JSON API docs
options array

Configuration options.
↳ ifGenerationMatch string

Makes the operation conditional on whether the object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the object's current metageneration does not match the given value.
↳ predefinedAcl string

Predefined ACL to apply to the object. Acceptable values include, "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", and "publicRead".
↳ retention array

The full list of available options are outlined at the JSON API docs.
↳ retention string

.retainUntilTime The earliest time in RFC 3339 UTC "Zulu" format that the object can be deleted or replaced. This is the retention configuration set for this object.
↳ retention string

.mode The mode of the retention configuration, which can be either "Unlocked" or "Locked".
↳ overrideUnlockedRetention bool

Applicable for objects that have an unlocked retention configuration. Required to be set to true if the operation includes a retention property that changes the mode to Locked, reduces the retainUntilTime, or removes the retention configuration from the object.
↳ 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.
Returns
Type Description
array

copy

See also:

Parameters
Name Description
destination Bucket|string

The destination bucket.
options array

Configuration options.
↳ name string

The name of the destination object. Defaults to the name of the source object.
↳ predefinedAcl string

Predefined ACL to apply to the object. Acceptable values include, "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", and "publicRead".
↳ encryptionKey string

A base64 encoded AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation.
↳ encryptionKeySHA256 string

Base64 encoded SHA256 hash of the customer-supplied encryption key. This value will be calculated from the encryptionKey on your behalf if not provided, but for best performance it is recommended to pass in a cached version of the already calculated SHA.
↳ ifGenerationMatch string

Makes the operation conditional on whether the destination object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the destination object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the destination object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the destination object's current metageneration does not match the given value.
↳ ifSourceGenerationMatch string

Makes the operation conditional on whether the source object's current generation matches the given value.
↳ ifSourceGenerationNotMatch string

Makes the operation conditional on whether the source object's current generation does not match the given value.
↳ ifSourceMetagenerationMatch string

Makes the operation conditional on whether the source object's current metageneration matches the given value.
↳ ifSourceMetagenerationNotMatch string

Makes the operation conditional on whether the source object's current metageneration does not match the given value.
Returns
Type Description
StorageObject

rewrite

See also:

Parameters
Name Description
destination Bucket|string

The destination bucket.
options array

Configuration options.
↳ name string

The name of the destination object. Defaults to the name of the source object.
↳ predefinedAcl string

Predefined ACL to apply to the object. Acceptable values include, "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", and "publicRead".
↳ maxBytesRewrittenPerCall string

The maximum number of bytes that will be rewritten per rewrite request. Most callers shouldn't need to specify this parameter - it is primarily in place to support testing. If specified the value must be an integral multiple of 1 MiB (1048576). Also, this only applies to requests where the source and destination span locations and/or storage classes.
↳ encryptionKey string

A base64 encoded AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation.
↳ encryptionKeySHA256 string

Base64 encoded SHA256 hash of the customer-supplied encryption key. This value will be calculated from the encryptionKey on your behalf if not provided, but for best performance it is recommended to pass in a cached version of the already calculated SHA.
↳ destinationEncryptionKey string

A base64 encoded AES-256 customer-supplied encryption key that will be used to encrypt the rewritten object.
↳ destinationEncryptionKeySHA256 string

Base64 encoded SHA256 hash of the customer-supplied destination encryption key. This value will be calculated from the destinationEncryptionKey on your behalf if not provided, but for best performance it is recommended to pass in a cached version of the already calculated SHA.
↳ destinationKmsKeyName string

Name of the Cloud KMS key that will be used to encrypt the object. 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 destination bucket.
↳ ifGenerationMatch string

Makes the operation conditional on whether the destination object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the destination object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the destination object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the destination object's current metageneration does not match the given value.
↳ ifSourceGenerationMatch string

Makes the operation conditional on whether the source object's current generation matches the given value.
↳ ifSourceGenerationNotMatch string

Makes the operation conditional on whether the source object's current generation does not match the given value.
↳ ifSourceMetagenerationMatch string

Makes the operation conditional on whether the source object's current metageneration matches the given value.
↳ ifSourceMetagenerationNotMatch string

Makes the operation conditional on whether the source object's current metageneration does not match the given value.
Returns
Type Description
StorageObject

rename

Renames the object.

Please note that there is no atomic rename provided by the Storage API. This method is for convenience and is a set of sequential calls to copy and delete. Upon success the source object's metadata will be cleared, please use the returned object instead.

Example:

$object2 = $object->rename('object2.txt');
echo $object2->name();
Parameters
Name Description
name string

The new name.
options array

Configuration options.
↳ predefinedAcl string

Predefined ACL to apply to the object. Acceptable values include, "authenticatedRead", "bucketOwnerFullControl", "bucketOwnerRead", "private", "projectPrivate", and "publicRead".
↳ encryptionKey string

A base64 encoded AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation.
↳ encryptionKeySHA256 string

Base64 encoded SHA256 hash of the customer-supplied encryption key. This value will be calculated from the encryptionKey on your behalf if not provided, but for best performance it is recommended to pass in a cached version of the already calculated SHA.
↳ ifGenerationMatch string

Makes the operation conditional on whether the destination object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the destination object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the destination object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the destination object's current metageneration does not match the given value.
↳ ifSourceGenerationMatch string

Makes the operation conditional on whether the source object's current generation matches the given value.
↳ ifSourceGenerationNotMatch string

Makes the operation conditional on whether the source object's current generation does not match the given value.
↳ ifSourceMetagenerationMatch string

Makes the operation conditional on whether the source object's current metageneration matches the given value.
↳ ifSourceMetagenerationNotMatch string

Makes the operation conditional on whether the source object's current metageneration does not match the given value.
↳ destinationBucket string

Will move to this bucket if set. If not set, will default to the same bucket.
Returns
Type Description
StorageObject The renamed object.

downloadAsString

See also:

Parameters
Name Description
options array

Configuration Options.
↳ encryptionKey string

An AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKeySHA256.
↳ encryptionKeySHA256 string

The SHA256 hash of the customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKey.
Returns
Type Description
string

downloadToFile

See also:

Parameters
Name Description
path string

Path to download the file to.
options array

Configuration Options.
↳ encryptionKey string

An AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKeySHA256.
↳ encryptionKeySHA256 string

The SHA256 hash of the customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKey.
Returns
Type Description
Psr\Http\Message\StreamInterface

downloadAsStream

See also:

Parameters
Name Description
options array

Configuration Options.
↳ encryptionKey string

An AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKeySHA256.
↳ encryptionKeySHA256 string

The SHA256 hash of the customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKey.
Returns
Type Description
Psr\Http\Message\StreamInterface

downloadAsStreamAsync

See also:

Parameters
Name Description
options array

Configuration Options.
↳ encryptionKey string

An AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKeySHA256.
↳ encryptionKeySHA256 string

The SHA256 hash of the customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation. If provided one must also include an encryptionKey.
Returns
Type Description
GuzzleHttp\Promise\PromiseInterface<Psr\Http\Message\StreamInterface>

signedUrl

See also:

Parameters
Name Description
expires Google\Cloud\Core\Timestamp|DateTimeInterface|int

Specifies when the URL will expire. May provide an instance of Google\Cloud\Core\Timestamp, http://php.net/datetimeimmutable, or a UNIX timestamp as an integer.
options array

Configuration Options.
↳ bucketBoundHostname string

The hostname for the bucket, for instance cdn.example.com. May be used for Google Cloud Load Balancers or for custom bucket CNAMEs. Defaults to storage.googleapis.com.
↳ contentMd5 string

The MD5 digest value in base64. If you provide this, the client must provide this HTTP header with this same value in its request. If provided, take care to always provide this value as a base64 encoded string.
↳ contentType string

If you provide this value, the client must provide this HTTP header set to the same value.
↳ forceOpenssl bool

If true, OpenSSL will be used regardless of whether phpseclib is available. Defaults to false.
↳ headers array

If additional headers are provided, the server will check to make sure that the client provides matching values. Provide headers as a key/value array, where the key is the header name, and the value is an array of header values. Headers with multiple values may provide values as a simple array, or a comma-separated string. For a reference of allowed headers, see Reference Headers. Header values will be trimmed of leading and trailing spaces, multiple spaces within values will be collapsed to a single space, and line breaks will be replaced by an empty string. V2 Signed URLs may not provide x-goog-encryption-key or x-goog-encryption-key-sha256 headers.
↳ keyFile array

Keyfile data to use in place of the keyfile with which the client was constructed. If $options.keyFilePath is set, this option is ignored.
↳ keyFilePath string

A path to a valid Keyfile to use in place of the keyfile with which the client was constructed.
↳ method string

One of GET, PUT or DELETE. Defaults to GET.
↳ responseDisposition string

The response-content-disposition parameter of the signed url.
↳ responseType string

The response-content-type parameter of the signed url. When the server contentType is null, this option may be used to control the content type of the response.
↳ saveAsName string

The filename to prompt the user to save the file as when the signed url is accessed. This is ignored if $options.responseDisposition is set.
↳ scheme string

Either http or https. Only used if a custom hostname is provided via $options.bucketBoundHostname. If a custom bucketBoundHostname is provided, defaults to http. In all other cases, defaults to https.
↳ scopes string|array

One or more authentication scopes to be used with a key file. This option is ignored unless $options.keyFile or $options.keyFilePath is set.
↳ queryParams array

Additional query parameters to be included as part of the signed URL query string. For allowed values, see Reference Headers.
↳ version string

One of "v2" or "v4". Defaults to "v2".
↳ virtualHostedStyle bool

If true, URL will be of form mybucket.storage.googleapis.com. If false, storage.googleapis.com/mybucket. Defaults to false.
Returns
Type Description
string

signedUploadUrl

Create a Signed Upload URL for this object.

This method differs from StorageObject::signedUrl() in that it allows you to initiate a new resumable upload session. This can be used to allow non-authenticated users to insert an object into a bucket.

In order to upload data, a session URI must be obtained by sending an HTTP POST request to the URL returned from this method. See the Cloud Storage Documentation for more information.

If you prefer to skip this initial step, you may find StorageObject::beginSignedUploadSession() to fit your needs. Note that beginSignedUploadSession() cannot be used with Google Cloud PHP's Signed URL Uploader, and does not support a configurable expiration date.

Example:

$url = $object->signedUploadUrl(new \DateTime('tomorrow'));

// Use Signed URLs v4
$url = $object->signedUploadUrl(new \DateTime('tomorrow'), [
    'version' => 'v4'
]);
Parameters
Name Description
expires Google\Cloud\Core\Timestamp|DateTimeInterface|int

Specifies when the URL will expire. May provide an instance of Google\Cloud\Core\Timestamp, http://php.net/datetimeimmutable, or a UNIX timestamp as an integer.
options array

Configuration Options.
↳ contentMd5 string

The MD5 digest value in base64. If you provide this, the client must provide this HTTP header with this same value in its request. If provided, take care to always provide this value as a base64 encoded string.
↳ contentType string

If you provide this value, the client must provide this HTTP header set to the same value.
↳ forceOpenssl bool

If true, OpenSSL will be used regardless of whether phpseclib is available. Defaults to false.
↳ headers array

If additional headers are provided, the server will check to make sure that the client provides matching values. Provide headers as a key/value array, where the key is the header name, and the value is an array of header values. Headers with multiple values may provide values as a simple array, or a comma-separated string. For a reference of allowed headers, see Reference Headers. Header values will be trimmed of leading and trailing spaces, multiple spaces within values will be collapsed to a single space, and line breaks will be replaced by an empty string. V2 Signed URLs may not provide x-goog-encryption-key or x-goog-encryption-key-sha256 headers.
↳ keyFile array

Keyfile data to use in place of the keyfile with which the client was constructed. If $options.keyFilePath is set, this option is ignored.
↳ keyFilePath string

A path to a valid Keyfile to use in place of the keyfile with which the client was constructed.
↳ responseDisposition string

The response-content-disposition parameter of the signed url.
↳ responseType string

The response-content-type parameter of the signed url. When the server contentType is null, this option may be used to control the content type of the response.
↳ saveAsName string

The filename to prompt the user to save the file as when the signed url is accessed. This is ignored if $options.responseDisposition is set.
↳ scheme string

Either http or https. Only used if a custom hostname is provided via $options.bucketBoundHostname. In all other cases, https is used. When a custom bucketBoundHostname is provided, defaults to http.
↳ scopes string|array

One or more authentication scopes to be used with a key file. This option is ignored unless $options.keyFile or $options.keyFilePath is set.
↳ queryParams array

Additional query parameters to be included as part of the signed URL query string. For allowed values, see Reference Headers.
↳ version string

One of "v2" or "v4". Defaults to "v2".
Returns
Type Description
string

beginSignedUploadSession

See also:

Parameters
Name Description
options array

Configuration Options.
↳ contentMd5 string

The MD5 digest value in base64. If you provide this, the client must provide this HTTP header with this same value in its request. If provided, take care to always provide this value as a base64 encoded string.
↳ contentType string

If you provide this value, the client must provide this HTTP header set to the same value.
↳ forceOpenssl bool

If true, OpenSSL will be used regardless of whether phpseclib is available. Defaults to false.
↳ headers array

If additional headers are provided, the server will check to make sure that the client provides matching values. Provide headers as a key/value array, where the key is the header name, and the value is an array of header values. Headers with multiple values may provide values as a simple array, or a comma-separated string. For a reference of allowed headers, see Reference Headers. Header values will be trimmed of leading and trailing spaces, multiple spaces within values will be collapsed to a single space, and line breaks will be replaced by an empty string. V2 Signed URLs may not provide x-goog-encryption-key or x-goog-encryption-key-sha256 headers.
↳ keyFile array

Keyfile data to use in place of the keyfile with which the client was constructed. If $options.keyFilePath is set, this option is ignored.
↳ keyFilePath string

A path to a valid Keyfile to use in place of the keyfile with which the client was constructed.
↳ origin string

Value of CORS header "Access-Control-Allow-Origin". Defaults to "*".
↳ scopes string|array

One or more authentication scopes to be used with a key file. This option is ignored unless $options.keyFile or $options.keyFilePath is set.
↳ queryParams array

Additional query parameters to be included as part of the signed URL query string. For allowed values, see Reference Headers.
↳ version string

One of "v2" or "v4". Defaults to "v2".
Returns
Type Description
string

info

See also:

Parameters
Name Description
options array

Configuration options.
↳ encryptionKey string

An AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation in order to retrieve the MD5 hash and CRC32C checksum. If provided one must also include an encryptionKeySHA256.
↳ encryptionKeySHA256 string

The SHA256 hash of the customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation in order to retrieve the MD5 hash and CRC32C checksum. If provided one must also include an encryptionKey.
↳ ifGenerationMatch string

Makes the operation conditional on whether the object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the object's current metageneration does not match the given value.
↳ projection string

Determines which properties to return. May be either 'full' or 'noAcl'.
Returns
Type Description
array

reload

See also:

Parameters
Name Description
options array

Configuration options.
↳ encryptionKey string

A base64 encoded AES-256 customer-supplied encryption key. It will be neccesary to provide this when a key was used during the object's creation.
↳ encryptionKeySHA256 string

Base64 encoded SHA256 hash of the customer-supplied encryption key. This value will be calculated from the encryptionKey on your behalf if not provided, but for best performance it is recommended to pass in a cached version of the already calculated SHA.
↳ ifGenerationMatch string

Makes the operation conditional on whether the object's current generation matches the given value.
↳ ifGenerationNotMatch string

Makes the operation conditional on whether the object's current generation does not match the given value.
↳ ifMetagenerationMatch string

Makes the operation conditional on whether the object's current metageneration matches the given value.
↳ ifMetagenerationNotMatch string

Makes the operation conditional on whether the object's current metageneration does not match the given value.
↳ projection string

Determines which properties to return. May be either 'full' or 'noAcl'.
Returns
Type Description
array

name

Retrieves the object's name.

Example:

echo $object->name();
Returns
Type Description
string

identity

Retrieves the object's identity.

Example:

echo $object->identity()['object'];
Returns
Type Description
array

gcsUri

Formats the object as a string in the following format: gs://{bucket-name}/{object-name}.

Example:

echo $object->gcsUri();
Returns
Type Description
string

Constants

DEFAULT_DOWNLOAD_URL

Value: \Google\Cloud\Storage\SigningHelper::DEFAULT_DOWNLOAD_HOST