Cloud Firestore Client - Class Transaction (1.31.0)

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

Represents a Firestore transaction.

This class should be accessed inside a transaction callable, obtained via Google\Cloud\Firestore\Google\Cloud\Firestore\FirestoreClient::runTransaction().

Note that method examples, while shown as being called directly for the sake of brevity, should be called only within the context of a transaction callable, as noted above.

Example:

use Google\Cloud\Firestore\FirestoreClient;
use Google\Cloud\Firestore\Transaction;

$firestore = new FirestoreClient();
$document = $firestore->document('users/john');
$firestore->runTransaction(function (Transaction $transaction) use ($document) {
    // Manage Transaction.
});

Methods

__construct

Parameters
Name	Description
`connection`	`Google\Cloud\Firestore\Connection\ConnectionInterface` A connection to Cloud Firestore.
`valueMapper`	`Google\Cloud\Firestore\ValueMapper` A Firestore Value Mapper.
`database`	`string` The database name.
`transaction`	`string` The transaction ID.

snapshot

Get a Document Snapshot.

Example:

$snapshot = $transaction->snapshot($document);

Parameters
Name	Description
`document`	`Google\Cloud\Firestore\DocumentReference` The document to retrieve.
`options`	`array` Configuration options.

Returns
Type	Description
`Google\Cloud\Firestore\DocumentSnapshot`

runAggregateQuery

Get an Aggregate Query Snapshot.

Example:

$snapshot = $transaction->runAggregateQuery($aggregateQuery);

Parameters
Name	Description
`aggregateQuery`	`Google\Cloud\Firestore\AggregateQuery` The aggregate query to retrieve.
`options`	`array` Configuration Options
`↳ readTime`	`Timestamp` Reads entities as they were at the given timestamp.

Returns
Type	Description
`Google\Cloud\Firestore\AggregateQuerySnapshot`

documents

Get a list of documents by their path.

The number of results generated will be equal to the number of documents requested, except in case of error.

Note that this method will always return instances of Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot, even if the documents requested do not exist. It is highly recommended that you check for existence before accessing document data.

Example:

$documents = $transaction->documents([
    'users/john',
    'users/dave'
]);

// To check whether a given document exists, use `DocumentSnapshot::exists()`.
$documents = $transaction->documents([
    'users/deleted-user'
]);

foreach ($documents as $document) {
    if (!$document->exists()) {
        echo $document->id() . ' Does Not Exist';
    }
}

Parameters
Name	Description
`paths`	`string[]\|array<Google\Cloud\Firestore\DocumentReference>` Any combination of string paths or DocumentReference instances.
`options`	`array` Configuration options.

Returns
Type	Description
`array<Google\Cloud\Firestore\DocumentSnapshot>`

runQuery

Run a Query inside the Transaction.

Example:

$results = $transaction->runQuery($query);

Parameters
Name	Description
`query`	`Google\Cloud\Firestore\Query` A Firestore Query.
`options`	`array` Configuration options.

Returns
Type	Description
`Google\Cloud\Firestore\QuerySnapshot`

create

Enqueue an operation to create a Firestore document.

Example:

$transaction->create($document, [
    'name' => 'John',
    'country' => 'USA'
]);

Parameters
Name	Description
`document`	`Google\Cloud\Firestore\DocumentReference` The document to create.
`fields`	`array` An array containing fields, where keys are the field names, and values are field values. Nested arrays are allowed. Note that unlike {@see \Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentReference::update()}, field paths are NOT supported by this method.

Returns
Type	Description
`Google\Cloud\Firestore\Transaction`

set

Enqueue an operation to modify or replace a Firestore document.

Example:

// In this example, all field not explicitly specified will be removed.
$transaction->set($document, [
    'name' => 'Johnny'
]);

// To specify MERGE over REPLACE, set `$options.merge` to `true`.
$transaction->set($document, [
    'name' => 'Johnny'
], [
    'merge' => true
]);

Parameters
Name	Description
`document`	`Google\Cloud\Firestore\DocumentReference` The document to modify or replace.
`fields`	`array` An array containing fields, where keys are the field names, and values are field values. Nested arrays are allowed. Note that unlike {@see \Google\Cloud\Firestore\Google\Cloud\Firestore\Transaction::update()}, field paths are NOT supported by this method.
`options`	`array` Configuration options.
`↳ merge`	`bool` If true, unwritten fields will be preserved. Otherwise, they will be overwritten (removed). Defaults to `false`.

Returns
Type	Description
`Google\Cloud\Firestore\Transaction`

update

Enqueue an update with field paths and values.

Merges provided data with data stored in Firestore.

Calling this method on a non-existent document will raise an exception.

This method supports various sentinel values, to perform special operations on fields. Available sentinel values are provided as methods, found in Google\Cloud\Firestore\Google\Cloud\Firestore\FieldValue.

Note that field names must be provided using field paths, encoded either as a dot-delimited string (i.e. foo.bar), or an instance of Google\Cloud\Firestore\Google\Cloud\Firestore\FieldPath. Nested arrays are not allowed.

Please note that conflicting paths will result in an exception. Paths conflict when one path indicates a location nested within another path. For instance, path a.b cannot be set directly if path a is also provided.

Example:

$transaction->update($document, [
    ['path' => 'name', 'value' => 'John'],
    ['path' => 'country', 'value' => 'USA'],
    ['path' => 'cryptoCurrencies.bitcoin', 'value' => 0.5],
    ['path' => 'cryptoCurrencies.ethereum', 'value' => 10],
    ['path' => 'cryptoCurrencies.litecoin', 'value' => 5.51]
]);

// Google Cloud PHP provides special field values to enable operations such
// as deleting fields or setting the value to the current server timestamp.
use Google\Cloud\Firestore\FieldValue;

$transaction->update($document, [
    ['path' => 'country', 'value' => FieldValue::deleteField()],
    ['path' => 'lastLogin', 'value' => FieldValue::serverTimestamp()]
]);

// If your field names contain special characters (such as `.`, or symbols),
// using <xref uid="\Google\Cloud\Firestore\Google\Cloud\Firestore\FieldPath">Google\Cloud\Firestore\Google\Cloud\Firestore\FieldPath</xref> will properly escape each element.

use Google\Cloud\Firestore\FieldPath;

$transaction->update($document, [
    ['path' => new FieldPath(['cryptoCurrencies', 'big$$$coin']), 'value' => 5.51]
]);

Parameters
Name	Description
`document`	`Google\Cloud\Firestore\DocumentReference` The document to modify or replace.
`data`	`array[]` A list of arrays of form `[FieldPath\|string $path, mixed $value]`.
`options`	`array` Configuration options

Returns
Type	Description
`Google\Cloud\Firestore\Transaction`

delete

Enqueue an operation to delete a Firestore document.

Example:

$transaction->delete($document);

Parameters
Name	Description
`document`	`Google\Cloud\Firestore\DocumentReference` The document to delete.
`options`	`array` Configuration Options.

Returns
Type	Description
`Google\Cloud\Firestore\Transaction`

writer

Get the BulkWriter object.

Returns
Type	Description
`Google\Cloud\Firestore\BulkWriter`