Cloud Firestore Client - Class CollectionReference (1.30.0)

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

Represents a Cloud Firestore Collection.

Collections are implicit namespaces for Firestore Documents. They are created when the first document is inserted, and cease to exist when the last document is removed.

Example:

use Google\Cloud\Firestore\FirestoreClient;

$firestore = new FirestoreClient();
$collection = $firestore->collection('users');

Methods

__construct

Parameters
Name	Description
`connection`	`Google\Cloud\Firestore\Connection\ConnectionInterface` A Connection to Cloud Firestore.
`valueMapper`	`Google\Cloud\Firestore\ValueMapper` A Firestore Value Mapper.
`name`	`string` The absolute name of the collection.

name

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

Example:

$name = $collection->name();

Returns
Type	Description
`string`

path

Get the collection path.

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

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

Example:

$path = $collection->path();

Returns
Type	Description
`string`

id

Get the collection ID.

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\CollectionReference::name().

Example:

$id = $collection->id();

Returns
Type	Description
`string`

document

Get a reference to a document which is a direct child of this collection.

Example:

$newUser = $collection->document('john');

Parameter
Name	Description
`documentId`	`string` The document ID.

Returns
Type	Description
`Google\Cloud\Firestore\DocumentReference`

newDocument

Get a document reference with a randomly generated document ID.

If you wish to create a document reference with a specified name, use Google\Cloud\Firestore\Google\Cloud\Firestore\CollectionReference::document().

This method does NOT insert the document until you call Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentReference::create().

Example:

$newUser = $collection->newDocument();

Returns
Type	Description
`Google\Cloud\Firestore\DocumentReference`

add

Generate a new document reference, and insert it with the given field data.

This method will generate a random document name. If you wish to create a document with a specified name, create a reference with Google\Cloud\Firestore\Google\Cloud\Firestore\CollectionReference::document(), then call Google\Cloud\Firestore\Google\Cloud\Firestore\DocumentReference::create() to insert the document.

This method immediately inserts the document. If you wish for lazy creation of a Document instance, refer to Google\Cloud\Firestore\Google\Cloud\Firestore\CollectionReference::document() or Google\Cloud\Firestore\Google\Cloud\Firestore\CollectionReference::newDocument().

Example:

$newUser = $collection->add([
    'name' => 'Kate'
]);

Parameters
Name	Description
`fields`	`array` An array containing field names paired with their value. Accepts a nested array, or a simple array of field paths.
`options`	`array` Configuration Options.

Returns
Type	Description
`Google\Cloud\Firestore\DocumentReference`

listDocuments

List all documents in the collection.

Missing documents will be included in the result. A missing document is one which does not exist, but has sub-documents.

Example:

$documents = $collection->listDocuments();
foreach ($documents as $document) {
    echo $document->name() . PHP_EOL;
}

Parameters
Name	Description
`options`	`array` Configuration options
`↳ pageSize`	`int` The 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.

Returns
Type	Description
`Google\Cloud\Core\Iterator\ItemIterator<\google\cloud\firestore\documentreference>`

parent

Get the parent document reference for a subcollection, or null if root.

Example:

$parent = $collection->parent();

Returns
Type	Description
`Google\Cloud\Firestore\DocumentReference\|null`