chore(docs): Add clarification to Firestore MIGRATING.md (#8885)

* chore(docs): Add clarification to Firestore MIGRATING.md

* add client options changes

* document exceptions

* remove unused use

Author: bshaffer

Firestore/MIGRATING.md

@@ -2,13 +2,32 @@
 
 This document outlines the key breaking changes introduced in version 2 of the google-cloud-php Firestore library and provides guidance on how to update your code.
 
-## 1. Removal of the `Connection` Layer
+## 1. Client Options changes
+
+The following client options are removed/replaced with other options present in
+[`ClientOptions`][ClientOptions]. This was done to ensure client options are consistent across all
+Google Cloud clients.
+
+- `authCache` -> Moved to `credentialsConfig.authCache`
+- `authCacheOptions` -> Moved to `credentialsConfig.authCacheOptions`
+- `credentialsFetcher` -> Moved to `credentials`
+- `keyFile` -> Moved to `credentials`
+- `keyFilePath` -> Moved to `credentials`
+- `scopes` -> Moved to `credentialsConfig.scopes`
+- `quotaProject` -> Moved to `credentialsConfig.quotaProject`
+- `httpHandler` -> Moved to `transportConfig.rest.httpHandler`
+- `authHttpHandler` -> Moved to `credentialsConfig.authHttpHandler`
+
+## 2. Removal of the `Connection` Layer
 
 The most significant change in v2 is the removal of the `ConnectionInterface` and its `Grpc` implementation. All classes that previously depended on the connection layer now interact directly with the auto generated client for Firestore (`Google\Cloud\Firestore\V1\Client\FirestoreClient`).
 
 This change simplifies the library's architecture but requires updates to how you instantiate several core classes.
 
-## 2. Constructor Changes
+**Note**: If you primarily use factory methods (e.g. `$firestore->collection(...)`, `$collection->document(...)`), your
+code likely requires no changes, as the library handles these dependencies internally.
+
+## 3. Constructor Changes
 
 Due to the removal of the `Connection` layer, the constructors for the following classes have changed. They no longer accept a `ConnectionInterface` instance and instead require a `Google\Cloud\Firestore\V1\Client\FirestoreClient` instance.
 
@@ -58,7 +77,7 @@ $docRef = new DocumentReference(
 
 You will need to apply similar changes wherever you instantiate the classes listed above. The main `FirestoreClient` will now manage the GAPIC client instance.
 
-## 3. `WriteBatch` Class Removed
+## 4. `WriteBatch` Class Removed
 
 The `WriteBatch` class, which was previously a deprecated alias for `BulkWriter`, has been completely removed.
 

Firestore/src/AggregateQuery.php

@@ -20,6 +20,7 @@
 use Google\ApiCore\ApiException;
 use Google\ApiCore\Options\CallOptions;
 use Google\Cloud\Core\ApiHelperTrait;
+use Google\Cloud\Core\Exception\ServiceException;
 use Google\Cloud\Core\OptionsValidator;
 use Google\Cloud\Core\RequestProcessorTrait;
 use Google\Cloud\Firestore\V1\Client\FirestoreClient;
@@ -98,6 +99,7 @@ public function addAggregation($aggregate)
      *           {@see \Google\Cloud\Firestore\ExplainOptions}
      * }
      * @return AggregateQuerySnapshot
+     * @throws ServiceException
      */
     public function getSnapshot($options = [])
     {

Firestore/src/BulkWriter.php

@@ -21,6 +21,7 @@
 use Google\ApiCore\Options\CallOptions;
 use Google\Cloud\Core\ApiHelperTrait;
 use Google\Cloud\Core\DebugInfoTrait;
+use Google\Cloud\Core\Exception\ServiceException;
 use Google\Cloud\Core\OptionsValidator;
 use Google\Cloud\Core\RequestProcessorTrait;
 use Google\Cloud\Core\Timestamp;
@@ -665,6 +666,7 @@ public function flush($waitForRetryableFailures = false)
      * @param array $options Configuration Options
      * @return array [https://firebase.google.com/docs/firestore/reference/rpc/google.firestore.v1beta1#commitresponse](CommitResponse)
      * @codingStandardsIgnoreEnd
+     * @throws ServiceException
      */
     public function commit(array $options = []): array
     {
@@ -723,6 +725,7 @@ public function commit(array $options = []): array
      * @param array $options Configuration Options
      * @return void
      * @throws \RuntimeException If no transaction ID is provided at class construction.
+     * @throws ServiceException
      */
     public function rollback(array $options = []): void
     {
@@ -928,6 +931,7 @@ private function createWritesBatchIds($waitForRetryableFailures = false)
      *           Labels associated with this batch write.
      * }
      * @return array [https://firebase.google.com/docs/firestore/reference/rpc/google.firestore.v1beta1#BatchWriteResponse](BatchWriteResponse)
+     * @throws ServiceException
      */
     private function sendBatch(array $writes, array $options = [])
     {

Firestore/src/FirestoreClient.php

@@ -25,7 +25,6 @@
 use Google\Cloud\Core\DetectProjectIdTrait;
 use Google\Cloud\Core\EmulatorTrait;
 use Google\Cloud\Core\Exception\AbortedException;
-use Google\Cloud\Core\Exception\GoogleException;
 use Google\Cloud\Core\GeoPoint;
 use Google\Cloud\Core\Iterator\ItemIterator;
 use Google\Cloud\Core\Iterator\PageIterator;
@@ -177,7 +176,6 @@ class FirestoreClient
      *           The service domain for the client. Defaults to 'googleapis.com'.
      * }
      * @throws \InvalidArgumentException
-     * @throws GoogleException If the gRPC extension is not enabled.
      */
     public function __construct(array $config = [])
     {

Firestore/src/SnapshotTrait.php

@@ -21,6 +21,7 @@
 use Google\ApiCore\Options\CallOptions;
 use Google\Cloud\Core\ApiHelperTrait;
 use Google\Cloud\Core\Exception\NotFoundException;
+use Google\Cloud\Core\Exception\ServiceException;
 use Google\Cloud\Core\RequestProcessorTrait;
 use Google\Cloud\Core\Timestamp;
 use Google\Cloud\Core\TimestampTrait;
@@ -109,6 +110,7 @@ private function createSnapshotWithData(
      * @throws \InvalidArgumentException if an invalid `$options.readTime` is
      *     specified.
      * @throws NotFoundException If the document does not exist.
+     * @throws ServiceException
      */
     private function getSnapshot(FirestoreClient $gapicClient, $name, array $options = []): array
     {
@@ -159,6 +161,7 @@ private function getSnapshot(FirestoreClient $gapicClient, $name, array $options
      *        firestore document paths or DocumentReference instances.
      * @param array $options Configuration options.
      * @return DocumentSnapshot[]
+     * @throws ServiceException
      */
     private function getDocumentsByPaths(
         FirestoreClient $gapicClient,