Add support for setting additional options when creating the Firestor…

…e component
kreait · Nov 25, 2023 · 81eb1d7 · 81eb1d7
1 parent de493e2
commit 81eb1d7
Show file tree

Hide file tree

Showing 4 changed files with 121 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,13 @@ Please read about the future of the Firebase Admin PHP SDK on the
 
 ## [Unreleased]
 
+### Added
+
+* Added `Kreait\Firebase\Factory::withFirestoreClientConfig()` to support setting additional options when 
+  creating the Firestore component.
+* Added `Kreait\Firebase\Factory::withFirestoreDatabase()` to specify the database used when creating the Firestore 
+  component.
+
 ## [7.7.0] - 2023-11-25
 
 ### Changed
@@ -26,7 +33,7 @@ Please read about the future of the Firebase Admin PHP SDK on the
   }
 }
 ```
-    
+
 
 ## [7.6.0] - 2023-09-07
 

diff --git a/docs/cloud-firestore.rst b/docs/cloud-firestore.rst
@@ -65,3 +65,63 @@ Getting started
 
 ``$database`` is an instance of ``Google\Cloud\Firestore\FirestoreClient``. Please refer to the links above for
 guidance on how to proceed from here.
+
+******************************
+Use another Firestore Database
+******************************
+
+If you don't specify a database, the Firestore Client will connect to the ``(default)`` database.
+
+If you want to connect to another database, you can specify its name with the factory. You can work with multiple
+Firestore Databases simultaneously.
+
+.. code-block:: php
+
+    use Kreait\Firebase\Factory;
+
+    $factory = new Factory();
+
+    $defaultDatabase = $factory
+        ->createFirestore()
+        ->database();
+
+    $otherDatabase = $factory
+        ->withFirestoreDatabase('another-database')
+        ->createFirestore()
+        ->database();
+
+    $thirdDatabase = $factory
+        ->withFirestoreDatabase('third-database')
+        ->createFirestore()
+        ->database();
+
+***********************************
+Add Firestore configuration options
+***********************************
+
+You can add additional configuration options for the Firestore Client used by the Firestore component:
+
+.. code-block:: php
+
+    use Kreait\Firebase\Factory;
+
+    $factory = new Factory();
+
+    $firestore = $factory
+        ->withFirestoreClientConfig([...])
+        ->createFirestore();
+
+You can find all configuration options in the source code of the ``FirestoreClient`` class of the
+`official Google Firestore PHP library <https://github.com/googleapis/google-cloud-php-firestore/blob/4186f2a2f2a8bdaedf19376a35ccb0ffad17f4e1/src/FirestoreClient.php#L138>`_.
+
+In fact, the ``withFirestoreDatabase()`` method is a shortcut for the ``withFirestoreClientConfig()`` method:
+
+.. code-block:: php
+
+    use Kreait\Firebase\Factory;
+
+    $factory = new Factory();
+
+    $firestore = $factory->->withFirestoreDatabase('another-database');
+    // is a shortcut for
+    $firestore = $factory->withFirestoreClientConfig(['database' => 'another-database]);
diff --git a/src/Firebase/Factory.php b/src/Firebase/Factory.php
@@ -121,6 +121,11 @@ final class Factory
     private HttpFactory $httpFactory;
     private HttpClientOptions $httpClientOptions;
 
+    /**
+     * @var array<non-empty-string, mixed>
+     */
+    private array $firestoreClientConfig = [];
+
     public function __construct()
     {
         $this->clock = SystemClock::create();
@@ -228,6 +233,25 @@ public function withDatabaseAuthVariableOverride(?array $override): self
         return $factory;
     }
 
+    /**
+     * @param non-empty-string $database
+     */
+    public function withFirestoreDatabase(string $database): self
+    {
+        return $this->withFirestoreClientConfig(['database' => $database]);
+    }
+
+    /**
+     * @param array<non-empty-string, mixed> $config
+     */
+    public function withFirestoreClientConfig(array $config): self
+    {
+        $factory = clone $this;
+        $factory->firestoreClientConfig = array_merge($this->firestoreClientConfig, $config);
+
+        return $factory;
+    }
+
     /**
      * @param non-empty-string $name
      */
@@ -438,8 +462,10 @@ public function createDynamicLinksService($defaultDynamicLinksDomain = null): Co
 
     public function createFirestore(): Contract\Firestore
     {
+        $config = $this->googleCloudClientConfig() + $this->firestoreClientConfig;
+
         try {
-            $firestoreClient = new FirestoreClient($this->googleCloudClientConfig());
+            $firestoreClient = new FirestoreClient($config);
         } catch (Throwable $e) {
             throw new RuntimeException('Unable to create a FirestoreClient: '.$e->getMessage(), $e->getCode(), $e);
         }

diff --git a/tests/Integration/FactoryTest.php b/tests/Integration/FactoryTest.php
@@ -75,4 +75,30 @@ public function itSupportsAddingAdditionalHttpClientMiddlewares(): void
 
         $this->assertTrue($check);
     }
+
+    #[Test]
+    public function itSupportsOverridingTheDefaultFirestoreDatabase(): void
+    {
+        $firestore = self::$factory
+            ->withFirestoreDatabase(__FUNCTION__)
+            ->createFirestore();
+
+        $db = $firestore->database();
+        $name = $db->collection('irrelevant')->name();
+
+        $this->assertStringContainsString(__FUNCTION__, $name);
+    }
+
+    #[Test]
+    public function itSupportsAdditionalFirestoreConfig(): void
+    {
+        $firestore = self::$factory
+            ->withFirestoreClientConfig(['database' => __FUNCTION__])
+            ->createFirestore();
+
+        $db = $firestore->database();
+        $name = $db->collection('irrelevant')->name();
+
+        $this->assertStringContainsString(__FUNCTION__, $name);
+    }
 }