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 |
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 |
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
|
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 |