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 \ StorageMethods
__construct
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:
exists
Check whether or not the object exists.
Example:
if ($object->exists()) {
echo 'Object exists!';
}
options
array
[optional] Configuration options.
bool
delete
See also:
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.
void
update
See also:
metadata
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"
.
↳ 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.
array
copy
See also:
destination
options
array
Configuration options.
↳ name
string
The name of the destination object. Defaults tothe 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.
rewrite
destination
options
array
Configuration options.
↳ name
string
The name of the destination object. Defaults tothe 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.
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();
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.
downloadAsString
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
.
string
downloadToFile
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
.
Psr\Http\Message\StreamInterface
downloadAsStream
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
.
Psr\Http\Message\StreamInterface
downloadAsStreamAsync
See also:
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
.
GuzzleHttp\Promise\PromiseInterface<\psr\http\message\streaminterface>
signedUrl
See also:
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
↳ 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
.
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'
]);
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
↳ 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"
.
string
beginSignedUploadSession
See also:
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"
.
string
info
See also:
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'.
array
reload
See also:
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'.
array
name
Retrieves the object's name.
Example:
echo $object->name();
string
identity
Retrieves the object's identity.
Example:
echo $object->identity()['object'];
array
gcsUri
Formats the object as a string in the following format: gs://{bucket-name}/{object-name}
.
Example:
echo $object->gcsUri();
string
Constants
DEFAULT_DOWNLOAD_URL
Value: \Google\Cloud\Storage\SigningHelper::DEFAULT_DOWNLOAD_HOST
