Cloud Storage Client - Class StorageObject (1.36.1)

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`	`Google\Cloud\Storage\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:

More about Access Control Lists

Returns
Type	Description
`Google\Cloud\Storage\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:

Objects delete API documentation.

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:

Objects patch API documentation.

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:

Objects copy API documentation.

Parameters
Name	Description
`destination`	`Google\Cloud\Storage\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
`Google\Cloud\Storage\StorageObject`

rewrite

See also:

Parameters
Name	Description
`destination`	`Google\Cloud\Storage\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
`Google\Cloud\Storage\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
`Google\Cloud\Storage\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:

Signed URLs

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 Google\Cloud\Storage\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 Google\Cloud\Storage\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:

Resumable Upload Best Practices

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:

Objects get API documentation.

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:

Objects get API documentation.

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