# Cloud Firestore Client - Class DocumentReference (2.2.0-RC1)

2.2.0-RC1 2.1.0 (latest) 2.0.2-RC1 1.55.0 1.54.4 1.53.1 1.52.0 1.51.0 1.50.0 1.48.1 1.47.3 1.46.0 1.45.2 1.44.1 1.43.3 1.40.0 1.39.0 1.38.0 1.37.7 1.36.1 1.35.0 1.34.0 1.33.0 1.32.0 1.31.0 1.30.0 1.28.0 1.27.3 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** |
| `firestoreClient` | `https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/V1.Client.FirestoreClient` An instance of the Firestore client. This object is created by FirestoreClient, and should not be instantiated outside of this client. |
| `valueMapper` | `ValueMapper` A Firestore Value Mapper. |
| `parent` | `https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/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:

- [DocumentReference::id()](https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/DocumentReference#_Google_Cloud_Firestore_DocumentReference__id__) Returns the last element.
- [DocumentReference::path()](https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/DocumentReference#_Google_Cloud_Firestore_DocumentReference__path__) Returns the path, relative to the database.

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
[DocumentReference::id()](https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/DocumentReference#_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
[DocumentReference::path()](https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/DocumentReference#_Google_Cloud_Firestore_DocumentReference__path__).

Example:

    $id = $document->id();

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `string` |   |

### create

See also:

- [Commit](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.Firestore.Commit)

| **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 [DocumentReference::update()](https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/DocumentReference#_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:

- [Commit](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.Firestore.Commit)

| **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 [DocumentReference::update()](https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/DocumentReference#_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:

- [Commit](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.Firestore.Commit)

| **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:

- [Commit](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.Firestore.Commit)

| **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:

- [BatchGetDocuments](https://cloud.google.com/firestore/docs/reference/rpc/google.firestore.v1beta1#google.firestore.v1beta1.Firestore.BatchGetDocuments)

| **Parameter** ||
|---|---|
| **Name** | **Description** |
| `options` | `array` Configuration Options |

| **Returns** ||
|---|---|
| **Type** | **Description** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/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** |
| `https://docs.cloud.google.com/php/docs/reference/cloud-core/latest/Iterator.ItemIterator.html<https://docs.cloud.google.com/php/docs/reference/cloud-firestore/latest/CollectionReference>` |   |