Cloud Firestore Client - Class DocumentReference (1.45.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');

Namespace

Google \ Cloud \ Firestore

Methods

__construct

Parameters
Name Description
connection Google\Cloud\Firestore\Connection\ConnectionInterface

A Connection to Cloud Firestore. This object is created by FirestoreClient, and should not be instantiated outside of this client.
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
Type Description
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:

Example:

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

Example:

$path = $document->path();
Returns
Type Description
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\DocumentReference::path().

Example:

$id = $document->id();
Returns
Type Description
string

create

See also:

Parameters
Name Description
fields array

An array containing fields, where keys are the field names, and values are field values. Nested arrays are allowed. Note that unlike Google\Cloud\Firestore\DocumentReference::update(), field paths are NOT supported by this method.
options array

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

set

See also:

Parameters
Name Description
fields array

An array containing fields, where keys are the field names, and values are field values. Nested arrays are allowed. Note that unlike 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
Type Description
array [WriteResult](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.WriteResult)

update

See also:

Parameters
Name Description
data array[]

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

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

delete

See also:

Parameter
Name Description
options array

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

snapshot

See also:

Parameter
Name Description
options array

Configuration Options
Returns
Type Description
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
Name Description
collectionId string

The ID of the child collection.
Returns
Type Description
Google\Cloud\Firestore\CollectionReference

collections

List all collections which are children of the current document.

Example:

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

Configuration options.
Returns
Type Description
Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\firestore\collectionreference>