Skip to content

Commit 4a5f93d

Browse files
HectorhammettHectorhammett
authored
feat: Update Firestore to V2 (#8739)
1 parent 679f161 commit 4a5f93d

59 files changed

Lines changed: 3974 additions & 4284 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Core/tests/Unit/ServiceBuilderTest.php‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,6 @@
2020
use Google\Cloud\Core\ServiceBuilder;
2121
use Google\Cloud\Core\Testing\CheckForClassTrait;
2222
use Google\Cloud\Core\Testing\GrpcTestTrait;
23-
use Google\Cloud\Firestore\FirestoreClient;
2423
use Google\Cloud\Language\LanguageClient;
2524
use Google\Cloud\Logging\LoggingClient;
2625
use Google\Cloud\Storage\StorageClient;
@@ -145,11 +144,6 @@ public function serviceProvider()
145144
[
146145
'bigQuery',
147146
BigQueryClient::class
148-
],[
149-
'firestore',
150-
FirestoreClient::class,
151-
[],
152-
[$this, 'checkAndSkipGrpcTests']
153147
], [
154148
'logging',
155149
LoggingClient::class

‎Firestore/MIGRATING.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Migration Guide: v1 to v2
2+
3+
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.
4+
5+
## 1. Removal of the `Connection` Layer
6+
7+
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`).
8+
9+
This change simplifies the library's architecture but requires updates to how you instantiate several core classes.
10+
11+
## 2. Constructor Changes
12+
13+
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.
14+
15+
- `AggregateQuery`
16+
- `BulkWriter`
17+
- `CollectionReference`
18+
- `DocumentReference`
19+
- `FirestoreClient`
20+
- `FirestoreSessionHandler`
21+
- `Query`
22+
- `Transaction`
23+
- `ValueMapper`
24+
25+
**Migration Action:**
26+
27+
When creating instances of these classes, you must now pass a `Google\Cloud\Firestore\V1\Client\FirestoreClient` object instead of a `ConnectionInterface` object.
28+
29+
**Example: `DocumentReference`**
30+
31+
*Before (v1):*
32+
```php
33+
use Google\Cloud\Firestore\Connection\ConnectionInterface;
34+
use Google\Cloud\Firestore\ValueMapper;
35+
use Google\Cloud\Firestore\CollectionReference;
36+
37+
$docRef = new DocumentReference(
38+
$connection, // Instance of ConnectionInterface
39+
$valueMapper,
40+
$parent,
41+
$name
42+
);
43+
```
44+
45+
*After (v2):*
46+
```php
47+
use Google\Cloud\Firestore\V1\Client\FirestoreClient;
48+
use Google\Cloud\Firestore\ValueMapper;
49+
use Google\Cloud\Firestore\CollectionReference;
50+
51+
$docRef = new DocumentReference(
52+
$firestoreClient, // Instance of FirestoreClient
53+
$valueMapper,
54+
$parent,
55+
$name
56+
);
57+
```
58+
59+
You will need to apply similar changes wherever you instantiate the classes listed above. The main `FirestoreClient` will now manage the GAPIC client instance.
60+
61+
## 3. `WriteBatch` Class Removed
62+
63+
The `WriteBatch` class, which was previously a deprecated alias for `BulkWriter`, has been completely removed.
64+
65+
**Migration Action:**
66+
67+
If you are still using the `WriteBatch` class, you must update your code to use `BulkWriter` directly. The functionality is identical.
68+
69+
*Before (v1):*
70+
```php
71+
$batch = $firestore->batch();
72+
// or
73+
$batch = new WriteBatch(...);
74+
```
75+
76+
*After (v2):*
77+
```php
78+
$batch = $firestore->bulkWriter();
79+
// or
80+
$batch = new BulkWriter(...);
81+
```
82+
83+
## Summary of Key Changes
84+
85+
| Class/Method | v1 Status | v2 Status | Migration Action |
86+
|---|---|---|---|
87+
| `ConnectionInterface` | In Use | **Removed** | Refactor code to use `V1\Client\FirestoreClient`. Update constructor calls for dependent classes. |
88+
| `WriteBatch` | Deprecated | **Removed** | Replace `WriteBatch` with `BulkWriter`. |
89+
| Class Constructors | Accepted `ConnectionInterface` | Accept `V1\Client\FirestoreClient` | Update arguments passed to constructors. |
90+
91+
By addressing these key areas, you can successfully migrate your application to version 2 of the Firestore client library.

‎Firestore/composer.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
"require": {
77
"php": "^8.1",
88
"ext-grpc": "*",
9-
"google/cloud-core": "^1.57",
9+
"google/cloud-core": "^1.68.2",
1010
"google/gax": "^1.38.0",
1111
"ramsey/uuid": "^3.0|^4.0"
1212
},
@@ -16,7 +16,8 @@
1616
"squizlabs/php_codesniffer": "2.*",
1717
"phpdocumentor/reflection": "^5.3.3||^6.0",
1818
"phpdocumentor/reflection-docblock": "^5.3",
19-
"erusev/parsedown": "^1.6"
19+
"erusev/parsedown": "^1.6",
20+
"dg/bypass-finals": "^1.9"
2021
},
2122
"suggest": {
2223
"ext-protobuf": "Provides a significant increase in throughput over the pure PHP protobuf implementation. See https://cloud.google.com/php/grpc for installation instructions."

‎Firestore/phpunit.xml.dist‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<?xml version="1.0" encoding="UTF-8"?>
2-
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
2+
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd" bootstrap="tests/Unit/bootstrap.php">
33
<coverage>
44
<include>
55
<directory suffix=".php">src</directory>

‎Firestore/src/AggregateQuery.php‎

Lines changed: 47 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,14 @@
1717

1818
namespace Google\Cloud\Firestore;
1919

20-
use Google\Cloud\Firestore\Connection\ConnectionInterface;
20+
use Google\ApiCore\ApiException;
21+
use Google\ApiCore\Options\CallOptions;
22+
use Google\Cloud\Core\ApiHelperTrait;
23+
use Google\Cloud\Core\OptionsValidator;
24+
use Google\Cloud\Core\RequestProcessorTrait;
25+
use Google\Cloud\Firestore\V1\Client\FirestoreClient;
2126
use Google\Cloud\Firestore\V1\ExplainOptions;
27+
use Google\Cloud\Firestore\V1\RunAggregationQueryRequest;
2228
use InvalidArgumentException;
2329

2430
/**
@@ -36,49 +42,37 @@
3642
*/
3743
class AggregateQuery
3844
{
45+
use ApiHelperTrait;
3946
use QueryTrait;
47+
use RequestProcessorTrait;
4048

41-
/**
42-
* @var ConnectionInterface
43-
* @internal
44-
*/
45-
private $connection;
46-
47-
/**
48-
* @var array
49-
*/
50-
private $query;
51-
52-
/**
53-
* @var string
54-
*/
55-
private $parentName;
56-
57-
/**
58-
* @var array
59-
*/
60-
private $aggregates = [];
49+
private FirestoreClient $gapicClient;
50+
private array $query;
51+
private string $parentName;
52+
private array $aggregates = [];
53+
private Serializer $serializer;
54+
private OptionsValidator $optionsValidator;
6155

6256
/**
6357
* Create an aggregation query.
6458
*
65-
* @param ConnectionInterface $connection A Connection to Cloud Firestore.
66-
* This object is created by FirestoreClient,
67-
* and should not be instantiated outside of this client.
59+
* @param FirestoreClient $firestoreClient A FirestoreClient instance.
6860
* @param string $parent The parent of the query.
6961
* @param array $query Represents the underlying structured query.
7062
* @param Aggregate $aggregate Aggregation over the provided query.
7163
*/
7264
public function __construct(
73-
ConnectionInterface $connection,
65+
FirestoreClient $firestoreClient,
7466
$parent,
7567
array $query,
7668
Aggregate $aggregate
7769
) {
78-
$this->connection = $connection;
70+
$this->gapicClient = $firestoreClient;
7971
$this->parentName = $parent;
8072
$this->query = $query;
8173
$this->aggregates[] = $aggregate;
74+
$this->serializer = new Serializer();
75+
$this->optionsValidator = new OptionsValidator($this->serializer);
8276
}
8377

8478
/**
@@ -115,17 +109,37 @@ public function getSnapshot($options = [])
115109
);
116110
}
117111

112+
/** @var Aggregate $aggregate */
118113
foreach ($this->aggregates as $aggregate) {
119114
$parsedAggregates[] = $aggregate->getProps();
120115
}
121-
$snapshot = $this->connection->runAggregationQuery([
122-
'parent' => $this->parentName,
123-
'structuredAggregationQuery' => $this->aggregateQueryPrepare([
124-
'aggregates' => $this->aggregates
125-
] + $this->query),
126-
] + $options)->current();
127116

128-
return new AggregateQuerySnapshot($snapshot);
117+
$jsonStructuredAggregationQuery = $this->aggregateQueryPrepare([
118+
'aggregates' => $this->aggregates
119+
] + $this->query);
120+
121+
$options += [
122+
'structuredAggregationQuery' => $jsonStructuredAggregationQuery,
123+
'parent' => $this->parentName
124+
];
125+
126+
/**
127+
* @var RunAggregationQueryRequest $request
128+
* @var CallOptions $callOptions
129+
*/
130+
[$request, $callOptions] = $this->validateOptions(
131+
$options,
132+
new RunAggregationQueryRequest(),
133+
CallOptions::class
134+
);
135+
136+
try {
137+
$snapshot = $this->gapicClient->runAggregationQuery($request, $callOptions)->readAll()->current();
138+
} catch (ApiException $ex) {
139+
throw $this->convertToGoogleException($ex);
140+
}
141+
142+
return new AggregateQuerySnapshot($this->serializer->encodeMessage($snapshot));
129143
}
130144

131145
/**

‎Firestore/src/AggregateQuerySnapshot.php‎

Lines changed: 3 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -39,24 +39,9 @@ class AggregateQuerySnapshot
3939
{
4040
use TimeTrait;
4141

42-
/**
43-
* @var Timestamp
44-
*/
45-
private $readTime;
46-
47-
/**
48-
* @var array
49-
*/
50-
private $aggregateFields = [];
51-
52-
/**
53-
* @var string
54-
*/
55-
private $transaction;
56-
57-
/**
58-
* @var null|ExplainMetrics
59-
*/
42+
private Timestamp $readTime;
43+
private array $aggregateFields = [];
44+
private string $transaction;
6045
private null|ExplainMetrics $explainMetrics;
6146

6247
/**

0 commit comments

Comments
 (0)