Skip to content

Commit dd0ea54

Browse files
bshafferbshaffer
authored
chore: add MIGRATING.md for recently promoted 2.0 clients (#7658)
1 parent cae527e commit dd0ea54

14 files changed

Lines changed: 2053 additions & 0 deletions

File tree

‎AutoMl/MIGRATING.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Migrating Google Cloud Clients to the New Surface
2+
3+
**Document Summary**
4+
5+
* Google Cloud PHP Client Libraries are releasing new major versions (v2) to
6+
introduce new surface changes.
7+
* The PHP Team at Google has developed a tool to automatically upgrade clients
8+
(see [`ClientUpgradeFixer`][client_upgrade_fixer]).
9+
10+
## WHAT are the new Cloud Clients?
11+
12+
The new Cloud Clients are in the namespace `\Client\`, whereas the previous
13+
clients are one directory above with the same name. For example:
14+
15+
```php
16+
// This is the "new" client
17+
use Google\Cloud\AutoMl\V1\Client\AutoMlClient;
18+
19+
// This is the deprecated client (marked with @deprecated)
20+
use Google\Cloud\AutoMl\V1\AutoMlClient;
21+
```
22+
23+
The main difference is that RPC methods which used to take a varying number of
24+
required arguments plus an array of optional arguments, now only take a
25+
_single_ `Request` object:
26+
27+
```php
28+
// Create a client.
29+
$autoMlClient = new AutoMlClient();
30+
31+
// Prepare the request message.
32+
$dataset = new Dataset();
33+
$updateMask = new FieldMask();
34+
$request = (new UpdateDatasetRequest())
35+
->setDataset($dataset)
36+
->setUpdateMask($updateMask);
37+
38+
// Call the API and handle any network failures.
39+
try {
40+
/** @var Dataset $response */
41+
$response = $autoMlClient->updateDataset($request);
42+
printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
43+
} catch (ApiException $ex) {
44+
printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
45+
}
46+
```
47+
48+
### RPCs use CallOptions
49+
50+
The new surface RPC methods take an optional array of
51+
[CallOptions][call_options] as the second argument. These are similar to how
52+
the `$optionalArgs` were used in the previous surface, but the new `CallOptions`
53+
_only_ contain options for the call itself, whereas the previous `$optionalArgs`
54+
also held the optional fields for the request body:
55+
56+
```php
57+
// To set call-time options, such as headers, timeouts, and retry options,
58+
// pass them in as the second argument
59+
$callOptions = ['timeoutMillis' => 20];
60+
$response = $autoMlClient->updateDataset($request, $callOptions);
61+
```
62+
63+
[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php
64+
65+
### Requests have static `::build` methods
66+
67+
Using Request objects directly can make it more difficult to quickly draft out
68+
the necessary code to deliver an RPC. To mitigate this friction, a static
69+
`::build` method is now generated when one or more
70+
[method signature annotations](https://google.aip.dev/client-libraries/4232)
71+
exist on the RPC.
72+
73+
Any request which has recommended parameters defined in its proto will include a
74+
`::build` method, so that these parameters are easily discoverable:
75+
76+
```php
77+
// Create the RPC request using the static "::build" method
78+
$request = UpdateDatasetRequest::build($dataset, $updateMask);
79+
$response = $autoMlClient->updateDataset($request);
80+
```
81+
82+
## HOW should I upgrade?
83+
84+
The changes are mostly straightforward, and at a minimum require the following:
85+
86+
- Update Google Cloud clients to use the new client namespace by appending
87+
`\Client` to the existing namespace.
88+
- Update RPC calls to accept the corresponding `Request` object.
89+
90+
**NOTE**: Client streaming calls do not require a `Request` object.
91+
92+
### Automatically upgrade code using the `ClientUpgradeFixer` tool
93+
94+
To help migrate code to the new client surface, we've written a
95+
[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match
96+
the new client surface. This tool is not guaranteed to work, so be sure to test
97+
everything that it changes thoroughly. Read more about how to install and run
98+
the tool in its [README][client_upgrade_fixer].
99+
100+
The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade
101+
code to use the new client surface:
102+
103+
```bash
104+
# run the CS fixer for that directory using the config above
105+
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project
106+
```
107+
108+
This will output a diff of the changes. Remove `--dry-run` from the above
109+
command to apply the changes automatically.
110+
111+
112+
```diff
113+
-use Google\Cloud\Dlp\V2\DlpServiceClient;
114+
+use Google\Cloud\Dlp\V2\Client\DlpServiceClient;
115+
+use Google\Cloud\Dlp\V2\CreateDlpJobRequest;
116+
use Google\Cloud\Dlp\V2\InspectConfig;
117+
use Google\Cloud\Dlp\V2\InspectJobConfig;
118+
use Google\Cloud\Dlp\V2\Likelihood;
119+
+use Google\Cloud\Dlp\V2\ListInfoTypesRequest;
120+
use Google\Cloud\Dlp\V2\StorageConfig;
121+
122+
// Instantiate a client.
123+
$dlp = new DlpServiceClient();
124+
125+
// optional args array (variable)
126+
-$infoTypes = $dlp->listInfoTypes($parent);
127+
+$request = (new ListInfoTypesRequest());
128+
+$infoTypes = $dlp->listInfoTypes($request);
129+
130+
// optional args array (inline array)
131+
-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']);
132+
+$request2 = (new CreateDlpJobRequest())
133+
+ ->setParent($parent)
134+
+ ->setJobId('abc')
135+
+ ->setLocationId('def');
136+
+$job = $dlp->createDlpJob($request2);
137+
```
138+
139+
[cs_fixer]: https://cs.symfony.com/
140+
[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md
141+
142+
## Feedback
143+
144+
Your feedback is important to us! Please continue to provide us with any
145+
thoughts and questions in the [Issues][google-cloud-issues] section of this
146+
repository.
147+
148+
[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues

‎BigQueryDataTransfer/MIGRATING.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# Migrating Google Cloud Clients to the New Surface
2+
3+
**Document Summary**
4+
5+
* Google Cloud PHP Client Libraries are releasing new major versions (v2) to
6+
introduce new surface changes.
7+
* The PHP Team at Google has developed a tool to automatically upgrade clients
8+
(see [`ClientUpgradeFixer`][client_upgrade_fixer]).
9+
10+
## WHAT are the new Cloud Clients?
11+
12+
The new Cloud Clients are in the namespace `\Client\`, whereas the previous
13+
clients are one directory above with the same name. For example:
14+
15+
```php
16+
// This is the "new" client
17+
use Google\Cloud\BigQuery\DataTransfer\V1\Client\DataTransferServiceClient;
18+
19+
// This is the deprecated client (marked with @deprecated)
20+
use Google\Cloud\BigQuery\DataTransfer\V1\DataTransferServiceClient;
21+
```
22+
23+
The main difference is that RPC methods which used to take a varying number of
24+
required arguments plus an array of optional arguments, now only take a
25+
_single_ `Request` object:
26+
27+
```php
28+
// Create a client.
29+
$dataTransferServiceClient = new DataTransferServiceClient();
30+
31+
// Prepare the request message.
32+
$request = new GetLocationRequest();
33+
34+
// Call the API and handle any network failures.
35+
try {
36+
/** @var Location $response */
37+
$response = $dataTransferServiceClient->getLocation($request);
38+
printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString());
39+
} catch (ApiException $ex) {
40+
printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
41+
}
42+
```
43+
44+
### RPCs use CallOptions
45+
46+
The new surface RPC methods take an optional array of
47+
[CallOptions][call_options] as the second argument. These are similar to how
48+
the `$optionalArgs` were used in the previous surface, but the new `CallOptions`
49+
_only_ contain options for the call itself, whereas the previous `$optionalArgs`
50+
also held the optional fields for the request body:
51+
52+
```php
53+
// To set call-time options, such as headers, timeouts, and retry options,
54+
// pass them in as the second argument
55+
$callOptions = ['timeoutMillis' => 20];
56+
$response = $dataTransferServiceClient->getLocation($request, $callOptions);
57+
```
58+
59+
[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php
60+
61+
### Requests have static `::build` methods
62+
63+
Using Request objects directly can make it more difficult to quickly draft out
64+
the necessary code to deliver an RPC. To mitigate this friction, a static
65+
`::build` method is now generated when one or more
66+
[method signature annotations](https://google.aip.dev/client-libraries/4232)
67+
exist on the RPC.
68+
69+
Any request which has recommended parameters defined in its proto will include a
70+
`::build` method, so that these parameters are easily discoverable:
71+
72+
```php
73+
// Create the RPC request using the static "::build" method
74+
$request = UpdateDatasetRequest::build($dataset, $updateMask);
75+
$response = $dataTransferServiceClient->getLocation($request);
76+
```
77+
78+
## HOW should I upgrade?
79+
80+
The changes are mostly straightforward, and at a minimum require the following:
81+
82+
- Update Google Cloud clients to use the new client namespace by appending
83+
`\Client` to the existing namespace.
84+
- Update RPC calls to accept the corresponding `Request` object.
85+
86+
**NOTE**: Client streaming calls do not require a `Request` object.
87+
88+
### Automatically upgrade code using the `ClientUpgradeFixer` tool
89+
90+
To help migrate code to the new client surface, we've written a
91+
[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match
92+
the new client surface. This tool is not guaranteed to work, so be sure to test
93+
everything that it changes thoroughly. Read more about how to install and run
94+
the tool in its [README][client_upgrade_fixer].
95+
96+
The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade
97+
code to use the new client surface:
98+
99+
```bash
100+
# run the CS fixer for that directory using the config above
101+
vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project
102+
```
103+
104+
This will output a diff of the changes. Remove `--dry-run` from the above
105+
command to apply the changes automatically.
106+
107+
108+
```diff
109+
-use Google\Cloud\Dlp\V2\DlpServiceClient;
110+
+use Google\Cloud\Dlp\V2\Client\DlpServiceClient;
111+
+use Google\Cloud\Dlp\V2\CreateDlpJobRequest;
112+
use Google\Cloud\Dlp\V2\InspectConfig;
113+
use Google\Cloud\Dlp\V2\InspectJobConfig;
114+
use Google\Cloud\Dlp\V2\Likelihood;
115+
+use Google\Cloud\Dlp\V2\ListInfoTypesRequest;
116+
use Google\Cloud\Dlp\V2\StorageConfig;
117+
118+
// Instantiate a client.
119+
$dlp = new DlpServiceClient();
120+
121+
// optional args array (variable)
122+
-$infoTypes = $dlp->listInfoTypes($parent);
123+
+$request = (new ListInfoTypesRequest());
124+
+$infoTypes = $dlp->listInfoTypes($request);
125+
126+
// optional args array (inline array)
127+
-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']);
128+
+$request2 = (new CreateDlpJobRequest())
129+
+ ->setParent($parent)
130+
+ ->setJobId('abc')
131+
+ ->setLocationId('def');
132+
+$job = $dlp->createDlpJob($request2);
133+
```
134+
135+
[cs_fixer]: https://cs.symfony.com/
136+
[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md
137+
138+
## Feedback
139+
140+
Your feedback is important to us! Please continue to provide us with any
141+
thoughts and questions in the [Issues][google-cloud-issues] section of this
142+
repository.
143+
144+
[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues

0 commit comments

Comments
 (0)