Cloud Firestore Client - Class FieldValue (1.31.0)

Reference documentation and code samples for the Cloud Firestore Client class FieldValue.

Provides special field values for Cloud Firestore.

This class cannot be instantiated, and methods contained within it should be accessed statically.

Methods

deleteField

Denotes a field which should be deleted from a Firestore Document.

This special value, when used as a field value on update calls, will cause the field to be entirely deleted from Cloud Firestore.

Example:

use Google\Cloud\Firestore\FieldValue;
use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient;
$document = $firestore->document('users/dave');
$document->update([
    [
        'path' => 'hometown',
        'value' => FieldValue::deleteField()
    ]
]);

Returns
Type	Description
`Google\Cloud\Firestore\FieldValue\DeleteFieldValue`

serverTimestamp

Denotes a field which should be set to the server timestamp.

This special value, when used as a field value on create, update or set calls, will cause the field value to be set to the current server timestamp.

Example:

use Google\Cloud\Firestore\FieldValue;
use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient;
$document = $firestore->document('users/dave');
$document->update([
    [
        'path' => 'lastLogin',
        'value' => FieldValue::serverTimestamp()
    ]
]);

Returns
Type	Description
`Google\Cloud\Firestore\FieldValue\ServerTimestampValue`

arrayUnion

Returns a special value that can be used with set(), create() or update() that tells the server to union the given elements with any array value that already exists on the server. Each specified element that doesn't already exist in the array will be added to the end. If the field being modified is not already an array it will be overwritten with an array containing exactly the specified elements.

Example:

use Google\Cloud\Firestore\FieldValue;
use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient;
$document = $firestore->document('users/dave');

$document->update([
    [
        'path' => 'favoriteColors',
        'value' => FieldValue::arrayUnion(['red', 'blue'])
    ]
]);

Parameter
Name	Description
`elements`	`array` The elements to union into the array.

Returns
Type	Description
`Google\Cloud\Firestore\FieldValue\ArrayUnionValue`

arrayRemove

Returns a special value that can be used with set(), create() or update() that tells the server to remove the given elements from any array value that already exists on the server. All instances of each element specified will be removed from the array. If the field being modified is not already an array it will be overwritten with an empty array.

Example:

use Google\Cloud\Firestore\FieldValue;
use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient;
$document = $firestore->document('users/dave');

$document->update([
    [
        'path' => 'favoriteColors',
        'value' => FieldValue::arrayRemove(['green'])
    ]
]);

Parameter
Name	Description
`elements`	`array` The elements to remove from the array.

Returns
Type	Description
`Google\Cloud\Firestore\FieldValue\ArrayRemoveValue`

increment

Returns a special value that can be used with set() or update() that tells the server to add the given value to the field's current value.

Given value must be an integer or a double value. If the field is not an integer or double, or if the field does not yet exist, the transformation will set the field to the given value. If either of the given value or the current field value are doubles, both values will be interpreted as doubles. Double arithmetic and representation of double values follow IEEE 754 semantics. If there is positive/negative integer overflow, the field is resolved to the largest magnitude positive/negative integer.

Example:

use Google\Cloud\Firestore\FieldValue;
use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient;
$document = $firestore->document('users/dave');

$document->update([
    [
        'path' => 'loginCount',
        'value' => FieldValue::increment(1)
    ]
]);

Parameter
Name	Description
`value`	`int\|float`

Returns
Type	Description
`Google\Cloud\Firestore\FieldValue\IncrementValue`