Cloud Storage Client - Class Lifecycle (1.45.0)

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

Object Lifecycle Management supports common use cases like setting a Time to Live (TTL) for objects, archiving older versions of objects, or "downgrading" storage classes of objects to help manage costs.

This builder does not execute any network requests and is intended to be used in combination with either StorageClient::createBucket() or Bucket::update().

Example:

// Access a builder preconfigured with rules already existing on a given
// bucket.
use Google\Cloud\Storage\StorageClient;

$storage = new StorageClient();
$bucket = $storage->bucket('my-bucket');
$lifecycle = $bucket->currentLifecycle();

// Or get a fresh builder by using the static factory method.
use Google\Cloud\Storage\Bucket;

$lifecycle = Bucket::lifecycle();

Namespace

Google \ Cloud \ Storage

Methods

__construct

Parameter
Name Description
lifecycle array

[optional] A lifecycle configuration. Please see here for the expected structure.

addDeleteRule

Adds an Object Lifecycle Delete Rule.

Example:

$lifecycle->addDeleteRule([
    'age' => 50,
    'isLive' => true
]);
Parameters
Name Description
condition array

The condition(s) where the rule will apply.
↳ age int

Age of an object (in days). This condition is satisfied when an object reaches the specified age.
↳ createdBefore DateTimeInterface|string

This condition is satisfied when an object is created before midnight of the specified date in UTC. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ customTimeBefore DateTimeInterface|string

This condition is satisfied when the custom time on an object is before this date in UTC. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ daysSinceCustomTime int

Number of days elapsed since the user-specified timestamp set on an object. The condition is satisfied if the days elapsed is at least this number. If no custom timestamp is specified on an object, the condition does not apply.
↳ daysSinceNoncurrentTime int

Number of days elapsed since the noncurrent timestamp of an object. The condition is satisfied if the days elapsed is at least this number. This condition is relevant only for versioned objects. The value of the field must be a nonnegative integer. If it's zero, the object version will become eligible for Lifecycle action as soon as it becomes noncurrent.
↳ isLive bool

Relevant only for versioned objects. If the value is true, this condition matches live objects; if the value is false, it matches archived objects.
↳ matchesStorageClass string[]

Objects having any of the storage classes specified by this condition will be matched. Values include "MULTI_REGIONAL", "REGIONAL", "NEARLINE", "ARCHIVE", "COLDLINE", "STANDARD", and "DURABLE_REDUCED_AVAILABILITY".
↳ noncurrentTimeBefore DateTimeInterface|string

This condition is satisfied when the noncurrent time on an object is before this timestamp. This condition is relevant only for versioned objects. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ numNewerVersions int

Relevant only for versioned objects. If the value is N, this condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.
↳ matchesPrefix string[]

Objects having names which start with values specified by this condition will be matched.
↳ matchesSuffix string[]

Objects having names which end with values specified by this condition will be matched.
Returns
Type Description
Lifecycle

addAbortIncompleteMultipartUploadRule

Adds a AbortIncompleteMultipartUpload lifecycle rule to Object Lifecycle.

Example:

$lifecycle->addAbortIncompleteMultipartUploadRule([
    'age' => 50,
    'isLive' => true
]);
Parameters
Name Description
condition array

The condition(s) where the rule will apply.
↳ age int

Age of an object (in days). This condition is satisfied when an object reaches the specified age.
↳ createdBefore DateTimeInterface|string

This condition is satisfied when an object is created before midnight of the specified date in UTC. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ customTimeBefore DateTimeInterface|string

This condition is satisfied when the custom time on an object is before this date in UTC. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ daysSinceCustomTime int

Number of days elapsed since the user-specified timestamp set on an object. The condition is satisfied if the days elapsed is at least this number. If no custom timestamp is specified on an object, the condition does not apply.
↳ daysSinceNoncurrentTime int

Number of days elapsed since the noncurrent timestamp of an object. The condition is satisfied if the days elapsed is at least this number. This condition is relevant only for versioned objects. The value of the field must be a nonnegative integer. If it's zero, the object version will become eligible for Lifecycle action as soon as it becomes noncurrent.
↳ isLive bool

Relevant only for versioned objects. If the value is true, this condition matches live objects; if the value is false, it matches archived objects.
↳ matchesStorageClass string[]

Objects having any of the storage classes specified by this condition will be matched. Values include "MULTI_REGIONAL", "REGIONAL", "NEARLINE", "ARCHIVE", "COLDLINE", "STANDARD", and "DURABLE_REDUCED_AVAILABILITY".
↳ noncurrentTimeBefore DateTimeInterface|string

This condition is satisfied when the noncurrent time on an object is before this timestamp. This condition is relevant only for versioned objects. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ numNewerVersions int

Relevant only for versioned objects. If the value is N, this condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.
↳ matchesPrefix string[]

Objects having names which start with values specified by this condition will be matched.
↳ matchesSuffix string[]

Objects having names which end with values specified by this condition will be matched.
Returns
Type Description
Lifecycle

addSetStorageClassRule

Adds an Object Lifecycle Set Storage Class Rule.

Example:

$lifecycle->addSetStorageClassRule('COLDLINE', [
    'age' => 50,
    'isLive' => true
]);

// Using customTimeBefore rule with an object's custom time setting.
$lifecycle->addSetStorageClassRule('NEARLINE', [
    'customTimeBefore' => (new \DateTime())->add(
        \DateInterval::createFromDateString('+10 days')
    )
]);

$bucket->update(['lifecycle' => $lifecycle]);

$object = $bucket->object($objectName);
$object->update([
    'metadata' => [
        'customTime' => '2020-08-17'
    ]
]);
Parameters
Name Description
storageClass string

The target storage class. Values include "MULTI_REGIONAL", "REGIONAL", "NEARLINE", "COLDLINE", "STANDARD", and "DURABLE_REDUCED_AVAILABILITY".
condition array

The condition(s) where the rule will apply.
↳ age int

Age of an object (in days). This condition is satisfied when an object reaches the specified age.
↳ createdBefore DateTimeInterface|string

This condition is satisfied when an object is created before midnight of the specified date in UTC. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ customTimeBefore DateTimeInterface|string

This condition is satisfied when the custom time on an object is before this date in UTC. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ daysSinceCustomTime int

Number of days elapsed since the user-specified timestamp set on an object. The condition is satisfied if the days elapsed is at least this number. If no custom timestamp is specified on an object, the condition does not apply.
↳ daysSinceNoncurrentTime int

Number of days elapsed since the noncurrent timestamp of an object. The condition is satisfied if the days elapsed is at least this number. This condition is relevant only for versioned objects. The value of the field must be a nonnegative integer. If it's zero, the object version will become eligible for Lifecycle action as soon as it becomes noncurrent.
↳ isLive bool

Relevant only for versioned objects. If the value is true, this condition matches live objects; if the value is false, it matches archived objects.
↳ matchesStorageClass string[]

Objects having any of the storage classes specified by this condition will be matched. Values include "MULTI_REGIONAL", "REGIONAL", "NEARLINE", "ARCHIVE", "COLDLINE", "STANDARD", and "DURABLE_REDUCED_AVAILABILITY".
↳ noncurrentTimeBefore DateTimeInterface|string

This condition is satisfied when the noncurrent time on an object is before this timestamp. This condition is relevant only for versioned objects. If a string is given, it must be a date in RFC 3339 format with only the date part (for instance, "2013-01-15").
↳ numNewerVersions int

Relevant only for versioned objects. If the value is N, this condition is satisfied when there are at least N versions (including the live version) newer than this version of the object.
↳ matchesPrefix string[]

Objects having names which start with values specified by this condition will be matched.
↳ matchesSuffix string[]

Objects having names which end with values specified by this condition will be matched.
Returns
Type Description
Lifecycle

clearRules

Clear all Object Lifecycle rules or rules of a certain action type.

Example:

// Remove all rules.
$lifecycle->clearRules();

// Remove all "Delete" based rules.
$lifecycle->clearRules('Delete');

// Clear any rules which have an age equal to 50.
$lifecycle->clearRules(function (array $rule) {
    return $rule['condition']['age'] === 50
        ? false
        : true;
});
Parameter
Name Description
action string|callable

[optional] If a string is provided, it must be the name of the type of rule to remove (SetStorageClass or Delete). All rules of this type will then be cleared. When providing a callable you may define a custom route for how you would like to remove rules. The provided callable will be run through array_filter. The callable's argument will be a single lifecycle rule as an associative array. When returning true from the callable the rule will be preserved, and if false it will be removed. Defaults to* null, clearing all assigned rules.
Returns
Type Description
Lifecycle

getIterator

Returns
Type Description
Generator

toArray

Returns
Type Description
array

offsetSet

Parameters
Name Description
offset string
value mixed

offsetExists

Parameter
Name Description
offset string
Returns
Type Description
bool

offsetUnset

Parameter
Name Description
offset string

offsetGet

Parameter
Name Description
offset string
Returns
Type Description
mixed