Add support for the Cloud Firestore Emulator (#1683)

Fixes #1681.

Firestore/src/Connection/Grpc.php

@@ -17,6 +17,7 @@
 
 namespace Google\Cloud\Firestore\Connection;
 
+use Google\Cloud\Core\EmulatorTrait;
 use Google\Cloud\Core\GrpcTrait;
 use Google\Cloud\Core\GrpcRequestWrapper;
 use Google\Cloud\Firestore\V1\FirestoreClient;
@@ -32,6 +33,7 @@
  */
 class Grpc implements ConnectionInterface
 {
+    use EmulatorTrait;
     use GrpcTrait;
 
     /**
@@ -78,6 +80,14 @@ public function __construct(array $config = [])
                 ? $config['authHttpHandler']
                 : null
         );
+
+        //@codeCoverageIgnoreStart
+        $config += ['emulatorHost' => null];
+        if ((bool) $config['emulatorHost']) {
+            $grpcConfig += $this->emulatorGapicConfig($config['emulatorHost']);
+        }
+        //@codeCoverageIgnoreEnd
+
         $this->firestore = new FirestoreClient($grpcConfig);
 
         $this->resourcePrefixHeader = FirestoreClient::databaseRootName(

Firestore/src/FirestoreClient.php

@@ -41,12 +41,33 @@
  * $ pecl install protobuf
  * ```
  *
+ * To enable the
+ * [Google Cloud Firestore Emulator](https://cloud.google.com/sdk/gcloud/reference/beta/emulators/firestore/),
+ * set the `FIRESTORE_EMULATOR_HOST` to the value provided by the gcloud command.
+ *
+ * Please note that Google Cloud PHP currently does not support IPv6 hostnames.
+ * If the Firestore emulator provides a IPv6 hostname, or a comma-separated list
+ * of both IPv6 and IPv4 names, be sure to set the environment variable to only
+ * an IPv4 address. The equivalent of `[::1]:8080`, for instance, would be
+ * `127.0.0.1:8080`.
+ *
  * Example:
  * ```
  * use Google\Cloud\Firestore\FirestoreClient;
  *
  * $firestore = new FirestoreClient();
  * ```
+ *
+ * ```
+ * // Using the Firestore Emulator
+ * use Google\Cloud\Firestore\FirestoreClient;
+ *
+ * // Be sure to use the port specified when starting the emulator.
+ * // `8900` is used as an example only.
+ * putenv('FIRESTORE_EMULATOR_HOST=localhost:8900');
+ *
+ * $firestore = new FirestoreClient();
+ * ```
  */
 class FirestoreClient
 {
@@ -111,11 +132,15 @@ class FirestoreClient
      */
     public function __construct(array $config = [])
     {
+        $emulatorHost = getenv('FIRESTORE_EMULATOR_HOST');
+
         $this->requireGrpc();
         $config += [
             'returnInt64AsObject' => false,
             'scopes' => [self::FULL_CONTROL_SCOPE],
-            'database' => self::DEFAULT_DATABASE
+            'database' => self::DEFAULT_DATABASE,
+            'hasEmulator' => (bool) $emulatorHost,
+            'emulatorHost' => $emulatorHost
         ];
 
         $this->database = $config['database'];

Firestore/tests/Snippet/FirestoreClientTest.php

@@ -245,4 +245,12 @@ public function testFieldPath()
         $res = $snippet->invoke('path');
         $this->assertInstanceOf(FieldPath::class, $res->returnVal());
     }
+
+    public function testEmulator()
+    {
+        $snippet = $this->snippetFromClass(FirestoreClient::class, 1);
+        $res = $snippet->invoke('firestore');
+        $this->assertInstanceOf(FirestoreClient::class, $res->returnVal());
+        $this->assertEquals('localhost:8900', getenv('FIRESTORE_EMULATOR_HOST'));
+    }
 }