Cloud Firestore Client - Class DocumentReference (1.30.0)

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

Represents a reference to a Firestore document.

Example:

use Google\Cloud\Firestore\FirestoreClient;

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

Methods

__construct

Parameters
NameDescription
connection Google\Cloud\Firestore\Connection\ConnectionInterface

A Connection to Cloud Firestore.

valueMapper Google\Cloud\Firestore\ValueMapper

A Firestore Value Mapper.

parent Google\Cloud\Firestore\CollectionReference

The collection in which this document is contained.

name string

The fully-qualified document name.

parent

Returns the parent collection.

Example:

$parent = $document->parent();
Returns
TypeDescription
Google\Cloud\Firestore\CollectionReference

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\DocumentReference::id() Returns the last element.
  • Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentReference::path() Returns the path, relative to the database.

Example:

$name = $document->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\DocumentReference::id().

Example:

$path = $document->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 path of a resource, relative to the database name, use Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentReference::path().

Example:

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

create

Create a new document in Firestore.

If the document already exists, this method will fail.

Example:

$document->create([
    'name' => 'John',
    'country' => 'USA'
]);
Parameters
NameDescription
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.

options array

Configuration Options.

Returns
TypeDescription
array[WriteResult](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.WriteResult)

set

Write to a Firestore document, with optional merge behavior.

This method will create the document if it does not already exist.

Unless $options.merge is set to true, this method will replace all existing document data.

Example:

$document->set([
    'name' => 'Dave'
]);
Parameters
NameDescription
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.

options array

Configuration Options

↳ merge bool

If true, unwritten fields will be preserved. Otherwise, they will be overwritten (removed). Defaults to false.

Returns
TypeDescription
array[WriteResult](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.WriteResult)

update

Update a Firestore document using 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:

$document->update([
    ['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;

$document->update([
    ['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;

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

A list of arrays of form [FieldPath|string $path, mixed $value].

options array

Configuration options

Returns
TypeDescription
array[WriteResult](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.WriteResult)

delete

Delete a Firestore document.

Example:

$document->delete();
Parameter
NameDescription
options array

Configuration Options

Returns
TypeDescription
array[WriteResult](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.WriteResult)

snapshot

Get a read-only snapshot of the document.

Example:

$snapshot = $document->snapshot();
Parameter
NameDescription
options array

Configuration Options

Returns
TypeDescription
Google\Cloud\Firestore\DocumentSnapshot

collection

Get a reference to a collection which is a child of the current document.

Example:

$child = $document->collection('wallet');
Parameter
NameDescription
collectionId string

The ID of the child collection.

Returns
TypeDescription
Google\Cloud\Firestore\CollectionReference

collections

List all collections which are children of the current document.

Example:

$collections = $document->collections();
Parameter
NameDescription
options array

Configuration options.

Returns
TypeDescription
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\firestore\collectionreference>