Firestore distributed counters samples (GoogleCloudPlatform#975)

Author: andrewinc

firestore/composer.json

@@ -24,9 +24,11 @@
             "src/end_at_field_query_cursor.php",
             "src/get_all.php",
             "src/get_all_docs.php",
+            "src/get_distributed_counter_value.php",
             "src/get_document.php",
             "src/get_multiple_docs.php",
             "src/initialize.php",
+            "src/initialize_distributed_counter.php",
             "src/initialize_project_id.php",
             "src/invalid_range_order_by_query.php",
             "src/invalid_range_query.php",
@@ -49,6 +51,7 @@
             "src/start_at_field_query_cursor.php",
             "src/start_at_snapshot_query_cursor.php",
             "src/subcollection_ref.php",
+            "src/update_distributed_counter.php",
             "src/update_doc.php",
             "src/update_doc_array.php",
             "src/update_nested_fields.php",

firestore/firestore.php

@@ -939,6 +939,57 @@
     })
 );
 
+//Create distributed counter
+$application->add((new Command('initialize-distributed-counter'))
+    ->setDefinition($inputDefinition)
+    ->setDescription('Creates a subcollection from the specified multiple shards.')
+    ->setHelp(<<
+The %command.name% command creates a distributed counter as a sub collection in Google Cloud Firestore, consisting of several empty shards.
+
+    php %command.full_name%
+
+EOF
+    )
+    ->setCode(function ($input, $output) {
+        $projectId = $input->getArgument('project');
+        initialize_distributed_counter($projectId);
+    })
+);
+
+//Increment (distributed counter)
+$application->add((new Command('update-distributed-counter'))
+    ->setDefinition($inputDefinition)
+    ->setDescription('Increments a randomly picked shard of a distributed counter.')
+    ->setHelp(<<
+The %command.name% command increments the randomly selected shard of a distributed counter using the Google Cloud Firestore API.
+
+    php %command.full_name%
+
+EOF
+    )
+    ->setCode(function ($input, $output) {
+        $projectId = $input->getArgument('project');
+        update_distributed_counter($projectId);
+    })
+);
+
+//get value (distributed counter)
+$application->add((new Command('get-distributed-counter-value'))
+    ->setDefinition($inputDefinition)
+    ->setDescription('Returns the total count across all the shards of a distributed counter.')
+    ->setHelp(<<
+The %command.name% command returns the total count across all the shards of a distributed counter, using the Google Cloud Firestore API.
+
+    php %command.full_name%
+
+EOF
+    )
+    ->setCode(function ($input, $output) {
+        $projectId = $input->getArgument('project');
+        get_distributed_counter_value($projectId);
+    })
+);
+
 // for testing
 if (getenv('PHPUNIT_TESTS') === '1') {
     return $application;

firestore/src/get_distributed_counter_value.php

@@ -0,0 +1,49 @@
+
+/**
+ * Copyright 2019 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/master/firestore/README.md
+ */
+
+namespace Google\Cloud\Samples\Firestore;
+
+use Google\Cloud\Firestore\FirestoreClient;
+
+/**
+ * Returns a total count across all shards of distributed counter.
+ * ```
+ * get_distributed_counter_value('your-project-id');
+ * ```
+ */
+function get_distributed_counter_value($projectId)
+{
+    // Create the Cloud Firestore client
+    $db = new FirestoreClient([
+        'projectId' => $projectId,
+    ]);
+    $ref = $db->collection('Shards_collection')->document('Distributed_counters');
+    # [START fs_get_distributed_counter_value]
+    $result = 0;
+    $docCollection = $ref->collection('SHARDS')->documents();
+    foreach ($docCollection as $doc) {
+        $result += $doc->data()['Cnt'];
+    }
+    # [END fs_get_distributed_counter_value]
+    printf('The current value of the distributed counter: %d' . PHP_EOL, $result);
+}

firestore/src/initialize_distributed_counter.php

@@ -0,0 +1,49 @@
+
+/**
+ * Copyright 2019 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/master/firestore/README.md
+ */
+
+namespace Google\Cloud\Samples\Firestore;
+
+use Google\Cloud\Firestore\FirestoreClient;
+
+/**
+ * Creates the specified multiple shards as a subcollection.
+ * ```
+ * initialize_distributed_counter('your-project-id');
+ * ```
+ */
+function initialize_distributed_counter($projectId)
+{
+    // Create the Cloud Firestore client
+    $db = new FirestoreClient([
+        'projectId' => $projectId,
+    ]);
+    $ref = $db->collection('Shards_collection')->document('Distributed_counters');
+    # [START fs_initialize_distributed_counter]
+    $numShards = 10;
+    $colRef = $ref->collection('SHARDS');
+    for ($i = 0; $i < $numShards; $i++) {
+        $doc = $colRef->document($i);
+        $doc->set(['Cnt' => 0]);
+    }
+    # [END fs_initialize_distributed_counter]
+}

firestore/src/update_distributed_counter.php

@@ -0,0 +1,55 @@
+
+/**
+ * Copyright 2019 Google LLC.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/master/firestore/README.md
+ */
+
+namespace Google\Cloud\Samples\Firestore;
+
+use Google\Cloud\Firestore\FieldValue;
+use Google\Cloud\Firestore\FirestoreClient;
+
+/**
+ * Increments a randomly picked shard of distributed counter.
+ * ```
+ * update_distributed_counter('your-project-id');
+ * ```
+ */
+function update_distributed_counter($projectId)
+{
+    // Create the Cloud Firestore client
+    $db = new FirestoreClient([
+        'projectId' => $projectId,
+    ]);
+    $ref = $db->collection('Shards_collection')->document('Distributed_counters');
+    # [START fs_update_distributed_counter]
+    $colRef = $ref->collection('SHARDS');
+    $numShards = 0;
+    $docCollection = $colRef->documents();
+    foreach ($docCollection as $doc) {
+        $numShards++;
+    }
+    $shardIdx = random_int(0, $numShards-1);
+    $doc = $colRef->document($shardIdx);
+    $doc->update([
+        ['path' => 'Cnt', 'value' => FieldValue::increment(1)]
+    ]);
+    # [END fs_update_distributed_counter]
+}

firestore/test/firestoreTest.php

@@ -17,6 +17,7 @@
 
 namespace Google\Cloud\Samples\Firestore\Tests;
 
+use Google\Cloud\Firestore\FirestoreClient;
 use Google\Cloud\TestUtils\TestTrait;
 use Google\Cloud\TestUtils\ExecuteCommandTrait;
 use PHPUnit\Framework\TestCase;
@@ -507,4 +508,38 @@ private function runFirestoreCommand($commandName)
             'project' => self::$firestoreProjectId
         ]);
     }
+
+    public function testDistributedCounter()
+    {
+        $this->runFirestoreCommand('initialize-distributed-counter');
+        $outputZero = $this->runFirestoreCommand('get-distributed-counter-value');
+        $this->assertContains('0', $outputZero);
+
+        //check count of shards
+        $db = new FirestoreClient([
+            'projectId' => self::$firestoreProjectId,
+        ]);
+        $ref = $db->collection('Shards_collection')->document('Distributed_counters');
+        $collect = $ref->collection('SHARDS');
+        $docCollection = $collect->documents();
+
+        $docIdList = [];
+        foreach ($docCollection as $docSnap) {
+            $docIdList[] = $docSnap->id();
+        }
+        $this->assertEquals(10, count($docIdList));
+
+        //call thrice and check the value
+        $this->runFirestoreCommand('update-distributed-counter');
+        $this->runFirestoreCommand('update-distributed-counter');
+        $this->runFirestoreCommand('update-distributed-counter');
+
+        $output = $this->runFirestoreCommand('get-distributed-counter-value');
+        $this->assertContains('3', $output);
+
+        //remove temporary data
+        foreach ($docIdList as $docId) {
+            $collect->document($docId)->delete();
+        }
+    }
 }