Skip to content

Commit 89ea735

Browse files
bshafferbshaffer
authored
chore(docs): add MIGRATING.md for v2 components and reference documentation (#7652)
* feat(docs): add v2 migrating page to reference documentation * add tests * remove accidental file * add individual MIGRATING.md files
1 parent 3eccacb commit 89ea735

45 files changed

Lines changed: 5899 additions & 2 deletions

File tree

Some content is hidden

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

‎AccessApproval/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\AccessApproval\V1\Client\AccessApprovalClient;
18+
19+
// This is the deprecated client (marked with @deprecated)
20+
use Google\Cloud\AccessApproval\V1\AccessApprovalClient;
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+
$accessApprovalClient = new AccessApprovalClient();
30+
31+
// Prepare the request message.
32+
$request = new GetAccessApprovalSettingsMessage();
33+
34+
// Call the API and handle any network failures.
35+
try {
36+
/** @var AccessApprovalSettings $response */
37+
$response = $accessApprovalClient->getAccessApprovalSettings($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 = $accessApprovalClient->getAccessApprovalSettings($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 = GetAccessApprovalSettingsMessage::build($name);
75+
$response = $accessApprovalClient->getAccessApprovalSettings($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

‎ApiGateway/MIGRATING.md‎

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

0 commit comments

Comments
 (0)