Cloud Firestore V1 Client - Class FirestoreClient (1.36.1)

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\Firestore\V1\Cursor;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function partition_query_sample(): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $firestoreClient->partitionQuery();

        /** @var Cursor $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

use Google\ApiCore\ApiException;
use Google\ApiCore\ServerStream;
use Google\Cloud\Firestore\V1\BatchGetDocumentsResponse;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $database         The database name. In the format:
 *                                 `projects/{project_id}/databases/{database_id}`.
 * @param string $documentsElement The names of the documents to retrieve. In the format:
 *                                 `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 *                                 The request will fail if any of the document is not a child resource of the
 *                                 given `database`. Duplicate names will be elided.
 */
function batch_get_documents_sample(string $database, string $documentsElement): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Prepare any non-scalar elements to be passed along with the request.
    $documents = [$documentsElement,];

    // Call the API and handle any network failures.
    try {
        /** @var ServerStream $stream */
        $stream = $firestoreClient->batchGetDocuments($database, $documents);

        /** @var BatchGetDocumentsResponse $element */
        foreach ($stream->readAll() as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $database = '[DATABASE]';
    $documentsElement = '[DOCUMENTS]';

    batch_get_documents_sample($database, $documentsElement);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\BatchWriteResponse;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function batch_write_sample(): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var BatchWriteResponse $response */
        $response = $firestoreClient->batchWrite();
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\BeginTransactionResponse;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $database The database name. In the format:
 *                         `projects/{project_id}/databases/{database_id}`.
 */
function begin_transaction_sample(string $database): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var BeginTransactionResponse $response */
        $response = $firestoreClient->beginTransaction($database);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $database = '[DATABASE]';

    begin_transaction_sample($database);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\CommitResponse;
use Google\Cloud\Firestore\V1\FirestoreClient;
use Google\Cloud\Firestore\V1\Write;

/**
 * @param string $database The database name. In the format:
 *                         `projects/{project_id}/databases/{database_id}`.
 */
function commit_sample(string $database): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Prepare any non-scalar elements to be passed along with the request.
    $writes = [new Write()];

    // Call the API and handle any network failures.
    try {
        /** @var CommitResponse $response */
        $response = $firestoreClient->commit($database, $writes);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $database = '[DATABASE]';

    commit_sample($database);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\Document;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $parent       The parent resource. For example:
 *                             `projects/{project_id}/databases/{database_id}/documents` or
 *                             `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}`
 * @param string $collectionId The collection ID, relative to `parent`, to list. For example:
 *                             `chatrooms`.
 * @param string $documentId   The client-assigned document ID to use for this document.
 *
 *                             Optional. If not specified, an ID will be assigned by the service.
 */
function create_document_sample(string $parent, string $collectionId, string $documentId): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Prepare any non-scalar elements to be passed along with the request.
    $document = new Document();

    // Call the API and handle any network failures.
    try {
        /** @var Document $response */
        $response = $firestoreClient->createDocument($parent, $collectionId, $documentId, $document);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $parent = '[PARENT]';
    $collectionId = '[COLLECTION_ID]';
    $documentId = '[DOCUMENT_ID]';

    create_document_sample($parent, $collectionId, $documentId);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $name The resource name of the Document to delete. In the format:
 *                     `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 */
function delete_document_sample(string $name): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        $firestoreClient->deleteDocument($name);
        printf('Call completed successfully.' . PHP_EOL);
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $name = '[NAME]';

    delete_document_sample($name);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\Document;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $name The resource name of the Document to get. In the format:
 *                     `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 */
function get_document_sample(string $name): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var Document $response */
        $response = $firestoreClient->getDocument($name);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $name = '[NAME]';

    get_document_sample($name);
}

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $parent The parent document. In the format:
 *                       `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 *                       For example:
 *                       `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
 */
function list_collection_ids_sample(string $parent): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $firestoreClient->listCollectionIds($parent);

        /** @var string $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element);
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $parent = '[PARENT]';

    list_collection_ids_sample($parent);
}

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\Firestore\V1\Document;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $parent       The parent resource name. In the format:
 *                             `projects/{project_id}/databases/{database_id}/documents` or
 *                             `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 *
 *                             For example:
 *                             `projects/my-project/databases/my-database/documents` or
 *                             `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
 * @param string $collectionId Optional. The collection ID, relative to `parent`, to list.
 *
 *                             For example: `chatrooms` or `messages`.
 *
 *                             This is optional, and when not provided, Firestore will list documents
 *                             from all collections under the provided `parent`.
 */
function list_documents_sample(string $parent, string $collectionId): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $firestoreClient->listDocuments($parent, $collectionId);

        /** @var Document $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $parent = '[PARENT]';
    $collectionId = '[COLLECTION_ID]';

    list_documents_sample($parent, $collectionId);
}

use Google\ApiCore\ApiException;
use Google\ApiCore\BidiStream;
use Google\Cloud\Firestore\V1\FirestoreClient;
use Google\Cloud\Firestore\V1\ListenRequest;
use Google\Cloud\Firestore\V1\ListenResponse;

/**
 * @param string $database The database name. In the format:
 *                         `projects/{project_id}/databases/{database_id}`.
 */
function listen_sample(string $database): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Prepare any non-scalar elements to be passed along with the request.
    $request = (new ListenRequest())
        ->setDatabase($database);

    // Call the API and handle any network failures.
    try {
        /** @var BidiStream $stream */
        $stream = $firestoreClient->listen();
        $stream->writeAll([$request,]);

        /** @var ListenResponse $element */
        foreach ($stream->closeWriteAndReadAll() as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $database = '[DATABASE]';

    listen_sample($database);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * @param string $database    The database name. In the format:
 *                            `projects/{project_id}/databases/{database_id}`.
 * @param string $transaction The transaction to roll back.
 */
function rollback_sample(string $database, string $transaction): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        $firestoreClient->rollback($database, $transaction);
        printf('Call completed successfully.' . PHP_EOL);
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $database = '[DATABASE]';
    $transaction = '...';

    rollback_sample($database, $transaction);
}

use Google\ApiCore\ApiException;
use Google\ApiCore\ServerStream;
use Google\Cloud\Firestore\V1\FirestoreClient;
use Google\Cloud\Firestore\V1\RunAggregationQueryResponse;

/**
 * @param string $parent The parent resource name. In the format:
 *                       `projects/{project_id}/databases/{database_id}/documents` or
 *                       `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 *                       For example:
 *                       `projects/my-project/databases/my-database/documents` or
 *                       `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
 */
function run_aggregation_query_sample(string $parent): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var ServerStream $stream */
        $stream = $firestoreClient->runAggregationQuery($parent);

        /** @var RunAggregationQueryResponse $element */
        foreach ($stream->readAll() as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $parent = '[PARENT]';

    run_aggregation_query_sample($parent);
}

use Google\ApiCore\ApiException;
use Google\ApiCore\ServerStream;
use Google\Cloud\Firestore\V1\FirestoreClient;
use Google\Cloud\Firestore\V1\RunQueryResponse;

/**
 * @param string $parent The parent resource name. In the format:
 *                       `projects/{project_id}/databases/{database_id}/documents` or
 *                       `projects/{project_id}/databases/{database_id}/documents/{document_path}`.
 *                       For example:
 *                       `projects/my-project/databases/my-database/documents` or
 *                       `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom`
 */
function run_query_sample(string $parent): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Call the API and handle any network failures.
    try {
        /** @var ServerStream $stream */
        $stream = $firestoreClient->runQuery($parent);

        /** @var RunQueryResponse $element */
        foreach ($stream->readAll() as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $parent = '[PARENT]';

    run_query_sample($parent);
}

use Google\ApiCore\ApiException;
use Google\Cloud\Firestore\V1\Document;
use Google\Cloud\Firestore\V1\DocumentMask;
use Google\Cloud\Firestore\V1\FirestoreClient;

/**
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function update_document_sample(): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Prepare any non-scalar elements to be passed along with the request.
    $document = new Document();
    $updateMask = new DocumentMask();

    // Call the API and handle any network failures.
    try {
        /** @var Document $response */
        $response = $firestoreClient->updateDocument($document, $updateMask);
        printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

use Google\ApiCore\ApiException;
use Google\ApiCore\BidiStream;
use Google\Cloud\Firestore\V1\FirestoreClient;
use Google\Cloud\Firestore\V1\WriteRequest;
use Google\Cloud\Firestore\V1\WriteResponse;

/**
 * @param string $database The database name. In the format:
 *                         `projects/{project_id}/databases/{database_id}`.
 *                         This is only required in the first message.
 */
function write_sample(string $database): void
{
    // Create a client.
    $firestoreClient = new FirestoreClient();

    // Prepare any non-scalar elements to be passed along with the request.
    $request = (new WriteRequest())
        ->setDatabase($database);

    // Call the API and handle any network failures.
    try {
        /** @var BidiStream $stream */
        $stream = $firestoreClient->write();
        $stream->writeAll([$request,]);

        /** @var WriteResponse $element */
        foreach ($stream->closeWriteAndReadAll() as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $database = '[DATABASE]';

    write_sample($database);
}