PHP Class Google\Cloud\Storage\StorageObject

Example: ``` use Google\Cloud\ServiceBuilder; $cloud = new ServiceBuilder(); $storage = $cloud->storage(); $bucket = $storage->bucket('my-bucket'); $object = $bucket->object('my-object');
Inheritance: use trait EncryptionTrait
ファイルを表示 Open project: GoogleCloudPlatform/gcloud-php Class Usage Examples

Protected Properties

Property Type Description
$connection Represents a connection to Cloud Storage.

Public Methods

Method Description
__construct ( Google\Cloud\Storage\Connection\ConnectionInterface $connection, string $name, string $bucket, string $generation = null, array $info = null, string $encryptionKey = null, string $encryptionKeySHA256 = null )
acl ( ) : Acl Configure ACL for this object.
copy ( Bucket | string $destination, array $options = [] ) : StorageObject Copy the object to a destination bucket.
delete ( array $options = [] ) : void Delete the object.
downloadAsStream ( array $options = [] ) : Psr\Http\Message\StreamInterface Download an object as a stream.
downloadAsString ( array $options = [] ) : string Download an object as a string.
downloadToFile ( string $path, array $options = [] ) : Psr\Http\Message\StreamInterface Download an object to a specified location.
exists ( ) : boolean Check whether or not the object exists.
identity ( ) : string Retrieves the object's identity.
info ( array $options = [] ) : array Retrieves the object's details. If no object data is cached a network request will be made to retrieve it.
name ( ) : string Retrieves the object's name.
reload ( array $options = [] ) : array Triggers a network request to reload the object's details.
rename ( string $name, array $options = [] ) : StorageObject Renames the object.
rewrite ( Bucket | string $destination, array $options = [] ) : StorageObject Rewrite the object to a destination bucket.
update ( array $metadata, array $options = [] ) : array Update the object. Upon receiving a result the local object's data will be updated.

Private Methods

Method Description
formatDestinationRequest ( string | Bucket $destination, array $options ) : array Formats a destination based request, such as copy or rewrite.

Method Details

__construct() public method

public __construct ( Google\Cloud\Storage\Connection\ConnectionInterface $connection, string $name, string $bucket, string $generation = null, array $info = null, string $encryptionKey = null, string $encryptionKeySHA256 = null )
$connection Google\Cloud\Storage\Connection\ConnectionInterface Represents a connection to Cloud Storage.
$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() public method

Example: $acl = $object->acl();
See also: https://cloud.google.com/storage/docs/access-control More about Access Control Lists
public acl ( ) : Acl
return Acl

copy() public method

Please note that if the destination bucket is the same as the source bucket and a new name is not provided the source object will be replaced with the copy of itself. Example: Provide your destination bucket as a string and retain the source object's name. $copiedObject = $object->copy('otherBucket'); Provide your destination bucket as a bucket object and choose a new name for the copied object. $otherBucket = $storage->bucket('otherBucket'); $copiedObject = $object->copy($otherBucket, [ 'name' => 'newFile.txt' ]);
See also: https://cloud.google.com/storage/docs/json_api/v1/objects/copy Objects copy API documentation.
public copy ( Bucket | string $destination, array $options = [] ) : StorageObject
$destination Bucket | string The destination bucket.
$options array [optional] { Configuration options. @type string $name The name of the destination object. **Defaults to** the name of the source object. @type string $predefinedAcl Access controls to apply to the destination object. Acceptable values include `authenticatedRead`, `bucketOwnerFullControl`, `bucketOwnerRead`, `private`, `projectPrivate`, and `publicRead`. @type string $encryptionKey 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. @type string $encryptionKeySHA256 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. @type string $ifGenerationMatch Makes the operation conditional on whether the destination object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the destination object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the destination object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the destination object's current metageneration does not match the given value. @type string $ifSourceGenerationMatch Makes the operation conditional on whether the source object's current generation matches the given value. @type string $ifSourceGenerationNotMatch Makes the operation conditional on whether the source object's current generation does not match the given value. @type string $ifSourceMetagenerationMatch Makes the operation conditional on whether the source object's current metageneration matches the given value. @type string $ifSourceMetagenerationNotMatch Makes the operation conditional on whether the source object's current metageneration does not match the given value. }
return StorageObject

delete() public method

Example: $object->delete();
See also: https://cloud.google.com/storage/docs/json_api/v1/objects/delete Objects delete API documentation.
public delete ( array $options = [] ) : void
$options array [optional] { Configuration options. @type string $ifGenerationMatch Makes the operation conditional on whether the object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the object's current metageneration does not match the given value. }
return void

downloadAsStream() public method

Example: $stream = $object->downloadAsStream(); echo $stream->getContents();
public downloadAsStream ( array $options = [] ) : Psr\Http\Message\StreamInterface
$options array [optional] { Configuration Options. @type string $encryptionKey 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`. @type string $encryptionKeySHA256 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`. }
return Psr\Http\Message\StreamInterface

downloadAsString() public method

Example: $string = $object->downloadAsString(); echo $string;
public downloadAsString ( array $options = [] ) : string
$options array [optional] { Configuration Options. @type string $encryptionKey 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`. @type string $encryptionKeySHA256 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`. }
return string

downloadToFile() public method

Example: $stream = $object->downloadToFile(__DIR__ . '/my-file.txt');
public downloadToFile ( string $path, array $options = [] ) : Psr\Http\Message\StreamInterface
$path string Path to download the file to.
$options array [optional] { Configuration Options. @type string $encryptionKey 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`. @type string $encryptionKeySHA256 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`. }
return Psr\Http\Message\StreamInterface

exists() public method

Example: if ($object->exists()) { echo "Object exists!"; }
public exists ( ) : boolean
return boolean

identity() public method

Example: echo $object->identity()['object'];
public identity ( ) : string
return string

info() public method

Example: $info = $object->info(); echo $info['size'];
See also: https://cloud.google.com/storage/docs/json_api/v1/objects/get Objects get API documentation.
public info ( array $options = [] ) : array
$options array [optional] { Configuration options. @type string $encryptionKey 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`. @type string $encryptionKeySHA256 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`. @type string $ifGenerationMatch Makes the operation conditional on whether the object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the object's current metageneration does not match the given value. @type string $projection Determines which properties to return. May be either 'full' or 'noAcl'. }
return array

name() public method

Example: echo $object->name();
public name ( ) : string
return string

reload() public method

Example: $object->reload(); $info = $object->info(); echo $info['location'];
See also: https://cloud.google.com/storage/docs/json_api/v1/objects/get Objects get API documentation.
public reload ( array $options = [] ) : array
$options array [optional] { Configuration options. @type string $encryptionKey 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. @type string $encryptionKeySHA256 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. @type string $ifGenerationMatch Makes the operation conditional on whether the object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the object's current metageneration does not match the given value. @type string $projection Determines which properties to return. May be either 'full' or 'noAcl'. }
return array

rename() public method

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();
public rename ( string $name, array $options = [] ) : StorageObject
$name string The new name.
$options array [optional] { Configuration options. @type string $predefinedAcl Access controls to apply to the destination object. Acceptable values include `authenticatedRead`, `bucketOwnerFullControl`, `bucketOwnerRead`, `private`, `projectPrivate`, and `publicRead`. @type string $encryptionKey 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. @type string $encryptionKeySHA256 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. @type string $ifGenerationMatch Makes the operation conditional on whether the destination object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the destination object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the destination object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the destination object's current metageneration does not match the given value. @type string $ifSourceGenerationMatch Makes the operation conditional on whether the source object's current generation matches the given value. @type string $ifSourceGenerationNotMatch Makes the operation conditional on whether the source object's current generation does not match the given value. @type string $ifSourceMetagenerationMatch Makes the operation conditional on whether the source object's current metageneration matches the given value. @type string $ifSourceMetagenerationNotMatch Makes the operation conditional on whether the source object's current metageneration does not match the given value. }
return StorageObject The renamed object.

rewrite() public method

This method copies data using multiple requests so large objects can be copied with a normal length timeout per request rather than one very long timeout for a single request. Please note that if the destination bucket is the same as the source bucket and a new name is not provided the source object will be replaced with the copy of itself. Example: Provide your destination bucket as a string and retain the source object's name. $rewrittenObject = $object->rewrite('otherBucket'); Provide your destination bucket as a bucket object and choose a new name for the copied object. $otherBucket = $storage->bucket('otherBucket'); $rewrittenObject = $object->rewrite($otherBucket, [ 'name' => 'newFile.txt' ]); Rotate customer-supplied encryption keys. $key = file_get_contents(__DIR__ . '/key.txt'); $destinationKey = base64_encode(openssl_random_pseudo_bytes(32)); // Make sure to remember your key. $rewrittenObject = $object->rewrite('otherBucket', [ 'encryptionKey' => $key, 'destinationEncryptionKey' => $destinationKey ]);
See also: https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite Objects rewrite API documentation.
See also: https://cloud.google.com/storage/docs/encryption#customer-supplied Customer-supplied encryption keys.
public rewrite ( Bucket | string $destination, array $options = [] ) : StorageObject
$destination Bucket | string The destination bucket.
$options array [optional] { Configuration options. @type string $name The name of the destination object. **Defaults to** the name of the source object. @type string $predefinedAcl Access controls to apply to the destination object. Acceptable values include `authenticatedRead`, `bucketOwnerFullControl`, `bucketOwnerRead`, `private`, `projectPrivate`, and `publicRead`. @type string $maxBytesRewrittenPerCall 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. @type string $encryptionKey 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. @type string $encryptionKeySHA256 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. @type string $destinationEncryptionKey A base64 encoded AES-256 customer-supplied encryption key that will be used to encrypt the rewritten object. @type string $destinationEncryptionKeySHA256 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. @type string $ifGenerationMatch Makes the operation conditional on whether the destination object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the destination object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the destination object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the destination object's current metageneration does not match the given value. @type string $ifSourceGenerationMatch Makes the operation conditional on whether the source object's current generation matches the given value. @type string $ifSourceGenerationNotMatch Makes the operation conditional on whether the source object's current generation does not match the given value. @type string $ifSourceMetagenerationMatch Makes the operation conditional on whether the source object's current metageneration matches the given value. @type string $ifSourceMetagenerationNotMatch Makes the operation conditional on whether the source object's current metageneration does not match the given value. }
return StorageObject

update() public method

Example: Add custom metadata to an existing object. $object->update([ 'metadata' => [ 'albumType' => 'family' ] ]);
See also: https://cloud.google.com/storage/docs/json_api/v1/objects/patch Objects patch API documentation.
public update ( array $metadata, array $options = [] ) : array
$metadata array The available options for metadata are outlined at the [JSON API docs](https://cloud.google.com/storage/docs/json_api/v1/objects#resource)
$options array [optional] { Configuration options. @type string $ifGenerationMatch Makes the operation conditional on whether the object's current generation matches the given value. @type string $ifGenerationNotMatch Makes the operation conditional on whether the object's current generation does not match the given value. @type string $ifMetagenerationMatch Makes the operation conditional on whether the object's current metageneration matches the given value. @type string $ifMetagenerationNotMatch Makes the operation conditional on whether the object's current metageneration does not match the given value. @type string $predefinedAcl Apply a predefined set of access controls to this object. @type string $projection Determines which properties to return. May be either 'full' or 'noAcl'. @type string $fields Selector which will cause the response to only return the specified fields. }
return array

Property Details

$connection protected_oe property

Represents a connection to Cloud Storage.
protected $connection