Cloud Firestore Client - Class DocumentSnapshot (1.30.0)

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

Represents the data of a document at the time of retrieval.

A snapshot is immutable and may point to a non-existing document.

Fields may be read in array-style syntax. Note that writing using array-style syntax is NOT supported and will result in a \BadMethodCallException.

Example:

use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient();
$document = $firestore->document('users/john');
$snapshot = $document->snapshot();
// Fields are exposed via array-style accessors:
$bitcoinWalletValue = $snapshot['wallet']['cryptoCurrency']['bitcoin'];

Methods

__construct

Parameters
NameDescription
reference Google\Cloud\Firestore\DocumentReference

The document which created the snapshot.

valueMapper Google\Cloud\Firestore\ValueMapper

A Firestore Value Mapper.

info array

Document information, such as create and update timestamps.

data array

Document field data.

exists bool

Whether the document exists in the Firestore database.

reference

Get the reference of the document which created the snapshot.

Example:

$reference = $snapshot->reference();
Returns
TypeDescription
Google\Cloud\Firestore\DocumentReference

name

Get the document name.

Names are absolute. The result of this call would be of the form projects/<project-id>/databases/<database-id>/documents/<relative-path>.

Other methods are available to retrieve different parts of a collection name:

  • Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot::id() Returns the last element.
  • Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot::path() Returns the path, relative to the database.

Example:

$name = $snapshot->name();
Returns
TypeDescription
string

path

Get the document path.

Paths identify the location of a document, relative to the database name.

To retrieve the document ID (the last element of the path), use Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot::id().

Example:

$path = $snapshot->path();
Returns
TypeDescription
string

id

Get the document identifier (i.e. the last path element).

IDs are the path element which identifies a resource. To retrieve the full path to a resource (the resource name), use Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentSnapshot::name().

Example:

$id = $snapshot->id();
Returns
TypeDescription
string

updateTime

Get the Document Update Timestamp.

Example:

$updateTime = $snapshot->updateTime();
Returns
TypeDescription
Google\Cloud\Core\Timestamp|null

readTime

Get the Document Read Timestamp.

Example:

$readTime = $snapshot->readTime();
Returns
TypeDescription
Google\Cloud\Core\Timestamp|null

createTime

Get the Document Create Timestamp.

Example:

$createTime = $snapshot->createTime();
Returns
TypeDescription
Google\Cloud\Core\Timestamp|null

data

Returns document data as an array, or null if the document does not exist.

Example:

$data = $snapshot->data();
Returns
TypeDescription
array|null

exists

Returns true if the document exists in the database.

Example:

if ($snapshot->exists()) {
    echo "The document exists!";
}
Returns
TypeDescription
bool

get

Get a field by field path.

A field path is a string containing the path to a specific field, at the top level or nested, delimited by .. For instance, the value hello in the structured field { "foo" : { "bar" : "hello" }} would be accessible using a field path of foo.bar.

Example:

$value = $snapshot->get('wallet.cryptoCurrency.bitcoin');
// Field names containing dots or symbols can be targeted using a FieldPath instance:
use Google\Cloud\Firestore\FieldPath;

$value = $snapshot->get(new FieldPath(['wallet', 'cryptoCurrency', 'my.coin']));
Parameter
NameDescription
fieldPath string|Google\Cloud\Firestore\FieldPath

The field path to return.

Returns
TypeDescription
mixed

offsetSet

Parameters
NameDescription
offset mixed
value mixed

offsetExists

Parameter
NameDescription
offset mixed

offsetUnset

Parameter
NameDescription
offset mixed

offsetGet

Parameter
NameDescription
offset mixed