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();
Namespace
Google \ Cloud \ FirestoreMethods
__construct
Create a Firestore client. Please note that this client requires the gRPC extension .
config
array
Configuration Options.
↳ projectId
string
The project ID from the Google Developer's Console.
↳ database
string
The database name to use, if different from the default.
↳ returnInt64AsObject
bool
If true, 64 bit integers will be returned as a Google\Cloud\Core\Int64 object for 32 bit platform compatibility. Defaults tofalse.
↳ firestoreClient
GapicFirestoreClient
A pre-instantiated client for the Firestore service.
↳ apiEndpoint
string
The address of the API remote host. May optionally include the port, formatted as "
↳ credentials
FetchAuthTokenInterface|CredentialsWrapper
This option should only be used with a pre-constructed Google\Auth\FetchAuthTokenInterface
or CredentialsWrapper
object. Note that when one of these objects are provided, any settings in $credentialsConfig will be ignored. Important: If you are providing a path to a credentials file, or a decoded credentials file as a PHP array, this usage is now DEPRECATED. Providing an unvalidated credential configuration to Google APIs can compromise the security of your systems and data. It is recommended to create the credentials explicitly use Google\Auth\Credentials\ServiceAccountCredentials; use Google\Cloud\Firestore\V1\FirestoreClient; $creds = new ServiceAccountCredentials($scopes, $json); $options = new FirestoreClient(['credentials' => $creds]);
https://cloud.google.com/docs/authentication/external/externally-sourced-credentials
↳ credentialsConfig
array
Options used to configure credentials, including auth token caching, for the client. For a full list of supporting configuration options, see Google\ApiCore\CredentialsWrapper::build() .
↳ disableRetries
bool
Determines whether or not retries defined by the client configuration should be disabled. Defaults to false
.
↳ clientConfig
string|array
Client method configuration, including retry settings. This option can be either a path to a JSON file, or a PHP array containing the decoded JSON data. By default this settings points to the default client config file, which is provided in the resources folder.
↳ transport
string|TransportInterface
The transport used for executing network requests. May be either the string rest
or grpc
. Defaults to grpc
if gRPC support is detected on the system. Advanced usage
: Additionally, it is possible to pass in an already instantiated Google\ApiCore\Transport\TransportInterface
object. Note that when this object is provided, any settings in $transportConfig, and any $apiEndpoint setting, will be ignored.
↳ transportConfig
array
Configuration options that will be used to construct the transport. Options for each supported transport type should be passed in a key for that transport. For example: $transportConfig = [ 'grpc' => [...], 'rest' => [...], ]; See the Google\ApiCore\Transport\GrpcTransport::build() and Google\ApiCore\Transport\RestTransport::build() methods for the supported options.
↳ clientCertSource
callable
A callable which returns the client cert as a string. This can be used to provide a certificate and private key to the transport layer for mTLS.
↳ logger
false|LoggerInterface
A PSR-3 compliant logger. If set to false, logging is disabled, ignoring the 'GOOGLE_SDK_PHP_LOGGING' environment flag
↳ universeDomain
string
The service domain for the client. Defaults to 'googleapis.com'.
bulkWriter
Get a Bulk Writer
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();
options
array
Configuration options.
Please note that the default values are experiementally derived after
performance evaluations. The underlying constants may change in backwards-
incompatible ways. Please use with caution, and test thoroughly when
upgrading.
↳ maxBatchSize
int
Maximum number of requests per batch. Defaults to 20
.
↳ greedilySend
bool
Flag to indicate whether BulkWriter greedily sends batches. Defaults to true
.
↳ isThrottlingEnabled
bool
Flag to indicate whether rate of sending writes can be throttled. Defaults to true
.
↳ initialOpsPerSecond
int
Initial number of operations per second. Defaults to 20
.
↳ maxOpsPerSecond
int
Maximum number of operations per second. Defaults to 500
.
↳ isRetryable
callable
Default retry handler for individial writes status code to be retried. Should accept error code and return true if retryable.
collection
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');
name
string
The name of the collection.
collections
See also:
options
array
Configuration options
↳ pageSize
int
Maximum number of results to return per request.
↳ resultLimit
int
Limit the number of results returned in total. Defaults to 0
(return all results).
↳ pageToken
string
A previously-returned page token used to resume the loading of results from a specific point.
document
Get a reference to a Firestore document.
Example:
$document = $firestore->document('users/john');
name
string
The document name or a path, relative to the database.
documents
See also:
paths
options
array
Configuration options.
collectionGroup
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!';
id
string
Identifies the collection to query over. Every collection or subcollection with this ID as the last segment of its path will be included. May not contain a slash.
runTransaction
See also:
callable
callable
A callable function, allowing atomic operations
against the Firestore API. Function signature should be of form: function (Transaction $t)
.
options
array
Configuration Options.
↳ begin
array
Configuration options for BeginTransaction.
↳ commit
array
Configuration options for Commit.
↳ rollback
array
Configuration options for rollback.
↳ maxRetries
int
The maximum number of times to retry failures. Defaults to 5
.
mixed
geoPoint
See also:
latitude
float
The latitude
longitude
float
The longitude
blob
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'));
value
string|resource| Psr\Http\Message\StreamInterface
The value to store in a blob.
fieldPath
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']);
fieldNames
array
A list of field names.
sessionHandler
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'];
options
array
Configuration Options.
↳ gcLimit
int
The number of entities to delete in the garbage collection. Values larger than 500 will be limited to 500. Defaults to 0
, indicating garbage collection is disabled by default.
↳ collectionNameTemplate
string
A sprintf compatible template for formatting the collection name where sessions will be stored. The template receives two values, the first being the save path and the latter being the session name.
↳ begin
array
Configuration options for beginTransaction.
↳ commit
array
Configuration options for commit.
↳ rollback
array
Configuration options for rollback.
↳ read
array
Configuration options for read.
↳ query
array
Configuration options for runQuery.
Constants
VERSION
Value: '2.0.0-RC1'
DEFAULT_DATABASE
Value: '(default)'
FULL_CONTROL_SCOPE
Value: 'https://www.googleapis.com/auth/cloud-platform'
MAX_RETRIES
Value: 5
