Cloud Firestore Client - Class FirestoreClient (1.30.0)

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

Cloud Firestore is a flexible, scalable, realtime database for mobile, web, and server development.

In production environments, it is highly recommended that you make use of the Protobuf PHP extension for improved performance. Protobuf can be installed via PECL.

$ pecl install protobuf

To enable the Google Cloud Firestore Emulator, set the FIRESTORE_EMULATOR_HOST to the value provided by the gcloud command.

Please note that Google Cloud PHP currently does not support IPv6 hostnames. If the Firestore emulator provides a IPv6 hostname, or a comma-separated list of both IPv6 and IPv4 names, be sure to set the environment variable to only an IPv4 address. The equivalent of [::1]:8080, for instance, would be 127.0.0.1:8080.

Example:

use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient();

// Using the Firestore Emulator
use Google\Cloud\Firestore\FirestoreClient;

// Be sure to use the port specified when starting the emulator.
// `8900` is used as an example only.
putenv('FIRESTORE_EMULATOR_HOST=localhost:8900');

$firestore = new FirestoreClient();

Create a Firestore client. Please note that this client requires the gRPC extension.

Get a Batch Writer

The Google\Cloud\Firestore\Google\Cloud\Firestore\WriteBatch allows more performant multi-document, atomic updates.

Example:

$batch = $firestore->batch();

Get a Bulk Writer

Google\Cloud\Firestore\Google\Cloud\Firestore\BulkWriter allows scheduling multiple writes with auto-retries in batches. Please note:

• This method is blocking and may execute many sequential batch write requests.
• Gradually ramps up writes as specified by the 500/50/5 rule.
• Does not guarantee the order of writes.
• Accepts unique document references only. Read more: Ramping up traffic

Example:

$batch = $firestore->bulkWriter();

Lazily instantiate a Collection reference.

Collections hold Firestore documents. Collections cannot be created or deleted directly - they exist only as implicit namespaces. Once no child documents remain in a collection, it ceases to exist.

Example:

$collection = $firestore->collection('users');

List root-level collections in the database.

Example:

$collections = $firestore->collections();

Get a reference to a Firestore document.

Example:

$document = $firestore->document('users/john');

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 = $firestore->documents([
    'users/john',
    'users/dave'
]);

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

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

Creates a new Query which includes all documents that are contained in a collection or subcollection with the given collection ID.

A collection group query with a collection ID of foo will return documents from /foo and /abc/dce/foo, but not /foo/abc/dce.

Example:

$query = $firestore->collectionGroup('users');
$querySnapshot = $query->documents();

echo $querySnapshot->size() . ' documents found!';

Executes a function in a Firestore transaction.

Transactions offer atomic operations, guaranteeing that either all writes will be applied, or none will be applied. The Google Cloud PHP Firestore client also handles automatic retry in cases where transactions fail due to a retryable error.

Transactions will be committed once the provided callable has finished execution. Thrown exceptions will prevent commit and trigger a rollback, and will bubble up to your level to be handled in whatever fashion is appropriate.

This method returns the return value of the given transaction callable.

Example:

use Google\Cloud\Firestore\Transaction;

$transferAmount = 500.00;
$from = $firestore->document('users/john');
$to = $firestore->document('users/dave');

$toNewBalance = $firestore->runTransaction(function (Transaction $t) use ($from, $to, $transferAmount) {
    $fromSnapshot = $t->snapshot($from);
    $toSnapshot = $t->snapshot($to);

    $fromNewBalance = $fromSnapshot['balance'] - $transferAmount;
    $toNewBalance = $toSnapshot['balance'] + $transferAmount;

    // If the transaction cannot be completed, throwing any exception
    // will trigger a rollback operation.
    if ($fromNewBalance < 0) {
        throw new \Exception('User 1 has insufficient funds!');
    }

    $t->update($from, [
        ['path' => 'balance', 'value' => $fromNewBalance]
    ])->update($to, [
        ['path' => 'balance', 'value' => $toNewBalance]
    ]);

    return $toNewBalance;
});

Create a new GeoPoint

Example:

$geoPoint = $firestore->geoPoint(37.4220, -122.0841);

Create a new Blob

Example:

$blob = $firestore->blob('hello world');

// Blobs can be used to store binary data
$blob = $firestore->blob(file_get_contents(__DIR__ .'/family-photo.jpg'));

Returns a FieldPath class, referring to a field in a document.

The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).

Example:

$path = $firestore->fieldPath(['accounts', 'usd']);

Returns a FirestoreSessionHandler.

Example:

$handler = $firestore->sessionHandler();

// Configure PHP to use the Firestore session handler.
session_set_save_handler($handler, true);
session_save_path('sessions');
session_start();

// Then write and read the $_SESSION array.
$_SESSION['name'] = 'Bob';
echo $_SESSION['name'];