diff --git a/AccessApproval/MIGRATING.md b/AccessApproval/MIGRATING.md new file mode 100644 index 000000000000..facd41ce08a1 --- /dev/null +++ b/AccessApproval/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\AccessApproval\V1\Client\AccessApprovalClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\AccessApproval\V1\AccessApprovalClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$accessApprovalClient = new AccessApprovalClient(); + +// Prepare the request message. +$request = new GetAccessApprovalSettingsMessage(); + +// Call the API and handle any network failures. +try { + /** @var AccessApprovalSettings $response */ + $response = $accessApprovalClient->getAccessApprovalSettings($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $accessApprovalClient->getAccessApprovalSettings($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = GetAccessApprovalSettingsMessage::build($name); +$response = $accessApprovalClient->getAccessApprovalSettings($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ApiGateway/MIGRATING.md b/ApiGateway/MIGRATING.md new file mode 100644 index 000000000000..aad16cd3d6fd --- /dev/null +++ b/ApiGateway/MIGRATING.md @@ -0,0 +1,156 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ApiGateway\V1\Client\ApiGatewayServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ApiGateway\V1\ApiGatewayServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$apiGatewayServiceClient = new ApiGatewayServiceClient(); + +// Prepare the request message. +$api = new Api(); +$request = (new UpdateApiRequest()) + ->setApi($api); + +// Call the API and handle any network failures. +try { + /** @var OperationResponse $response */ + $response = $apiGatewayServiceClient->updateApi($request); + $response->pollUntilComplete(); + + if ($response->operationSucceeded()) { + /** @var Api $result */ + $result = $response->getResult(); + printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString()); + } else { + /** @var Status $error */ + $error = $response->getError(); + printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $apiGatewayServiceClient->updateApi($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateApiRequest::build($api, $updateMask); +$response = $apiGatewayServiceClient->updateApi($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ApigeeConnect/MIGRATING.md b/ApigeeConnect/MIGRATING.md new file mode 100644 index 000000000000..ca995c5554bc --- /dev/null +++ b/ApigeeConnect/MIGRATING.md @@ -0,0 +1,149 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ApigeeConnect\V1\Client\ConnectionServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ApigeeConnect\V1\ConnectionServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$connectionServiceClient = new ConnectionServiceClient(); + +// Prepare the request message. +$request = (new ListConnectionsRequest()) + ->setParent($formattedParent); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $connectionServiceClient->listConnections($request); + + /** @var Connection $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $connectionServiceClient->listConnections($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListConnectionsRequest::build($parent); +$response = $connectionServiceClient->listConnections($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/AppEngineAdmin/MIGRATING.md b/AppEngineAdmin/MIGRATING.md new file mode 100644 index 000000000000..4f441c96f163 --- /dev/null +++ b/AppEngineAdmin/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\AppEngine\V1\Client\AuthorizedDomainsClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\AppEngine\V1\AuthorizedDomainsClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$authorizedDomainsClient = new AuthorizedDomainsClient(); + +// Prepare the request message. +$request = new ListAuthorizedDomainsRequest(); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $authorizedDomainsClient->listAuthorizedDomains($request); + + /** @var AuthorizedDomain $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $authorizedDomainsClient->listAuthorizedDomains($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListConnectionsRequest::build($parent); +$response = $authorizedDomainsClient->listAuthorizedDomains($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Asset/MIGRATING.md b/Asset/MIGRATING.md new file mode 100644 index 000000000000..89f6499c6ba3 --- /dev/null +++ b/Asset/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Asset\V1\Client\AssetServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Asset\V1\AssetServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$assetServiceClient = new AssetServiceClient(); + +// Prepare the request message. +$savedQuery = new SavedQuery(); +$updateMask = new FieldMask(); +$request = (new UpdateSavedQueryRequest()) + ->setSavedQuery($savedQuery) + ->setUpdateMask($updateMask); + +// Call the API and handle any network failures. +try { + /** @var SavedQuery $response */ + $response = $assetServiceClient->updateSavedQuery($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $assetServiceClient->updateSavedQuery($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateSavedQueryRequest::build($savedQuery, $updateMask); +$response = $assetServiceClient->updateSavedQuery($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/BigQueryConnection/MIGRATING.md b/BigQueryConnection/MIGRATING.md new file mode 100644 index 000000000000..7f846a42302b --- /dev/null +++ b/BigQueryConnection/MIGRATING.md @@ -0,0 +1,145 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\BigQuery\Connection\V1\Client\ConnectionServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\BigQuery\Connection\V1\ConnectionServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$connectionServiceClient = new ConnectionServiceClient(); + +// Prepare the request message. +$request = (new GetConnectionRequest()) + ->setName($formattedName); + +// Call the API and handle any network failures. +try { + /** @var Connection $response */ + $response = $connectionServiceClient->getConnection($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $connectionServiceClient->getConnection($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = GetConnectionRequest::build($name); +$response = $connectionServiceClient->getConnection($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/BigQueryReservation/MIGRATING.md b/BigQueryReservation/MIGRATING.md new file mode 100644 index 000000000000..df9783e0084d --- /dev/null +++ b/BigQueryReservation/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\BigQuery\Reservation\V1\Client\ReservationServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\BigQuery\Reservation\V1\ReservationServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$reservationServiceClient = new ReservationServiceClient(); + +// Prepare the request message. +$request = new UpdateReservationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Reservation $response */ + $response = $reservationServiceClient->updateReservation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $reservationServiceClient->updateReservation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateReservationRequest::build($reservation, $updateMask); +$response = $reservationServiceClient->updateReservation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/BigQueryStorage/MIGRATING.md b/BigQueryStorage/MIGRATING.md new file mode 100644 index 000000000000..57631f54fd07 --- /dev/null +++ b/BigQueryStorage/MIGRATING.md @@ -0,0 +1,149 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\BigQuery\Storage\V1\Client\BigQueryReadClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\BigQuery\Storage\V1\BigQueryReadClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$bigQueryReadClient = new BigQueryReadClient(); + +// Prepare the request message. +$request = (new ReadRowsRequest()) + ->setReadStream($formattedReadStream); + +// Call the API and handle any network failures. +try { + /** @var ServerStream $stream */ + $stream = $bigQueryReadClient->readRows($request); + + /** @var ReadRowsResponse $element */ + foreach ($stream->readAll() as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$stream = $bigQueryReadClient->readRows($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ReadRowsRequest::build($readStream, $offset); +$stream = $bigQueryReadClient->readRows($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Billing/MIGRATING.md b/Billing/MIGRATING.md new file mode 100644 index 000000000000..a029ef3de686 --- /dev/null +++ b/Billing/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Billing\V1\Client\CloudBillingClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Billing\V1\CloudBillingClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$cloudBillingClient = new CloudBillingClient(); + +// Prepare the request message. +$request = new ListBillingAccountsRequest(); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $cloudBillingClient->listBillingAccounts($request); + + /** @var BillingAccount $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $cloudBillingClient->listBillingAccounts($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ReadRowsRequest::build($readStream, $offset); +$response = $cloudBillingClient->listBillingAccounts($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/BillingBudgets/MIGRATING.md b/BillingBudgets/MIGRATING.md new file mode 100644 index 000000000000..33c5ba428e6d --- /dev/null +++ b/BillingBudgets/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Billing\Budgets\V1\Client\BudgetServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Billing\Budgets\V1\BudgetServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$budgetServiceClient = new BudgetServiceClient(); + +// Prepare the request message. +$budgetAmount = new BudgetAmount(); +$budget = (new Budget()) + ->setAmount($budgetAmount); +$request = (new UpdateBudgetRequest()) + ->setBudget($budget); + +// Call the API and handle any network failures. +try { + /** @var Budget $response */ + $response = $budgetServiceClient->updateBudget($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $budgetServiceClient->updateBudget($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateBudgetRequest::build($budget, $updateMask); +$response = $budgetServiceClient->updateBudget($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Channel/MIGRATING.md b/Channel/MIGRATING.md new file mode 100644 index 000000000000..258e0c077ff6 --- /dev/null +++ b/Channel/MIGRATING.md @@ -0,0 +1,149 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Channel\V1\Client\CloudChannelReportsServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Channel\V1\CloudChannelReportsServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$cloudChannelReportsServiceClient = new CloudChannelReportsServiceClient(); + +// Prepare the request message. +$request = (new ListReportsRequest()) + ->setParent($parent); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $cloudChannelReportsServiceClient->listReports($request); + + /** @var Report $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $cloudChannelReportsServiceClient->listReports($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListReportsRequest::build($parent); +$response = $cloudChannelReportsServiceClient->listReports($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ContactCenterInsights/MIGRATING.md b/ContactCenterInsights/MIGRATING.md new file mode 100644 index 000000000000..55a1c27bf767 --- /dev/null +++ b/ContactCenterInsights/MIGRATING.md @@ -0,0 +1,146 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ContactCenterInsights\V1\Client\ContactCenterInsightsClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ContactCenterInsights\V1\ContactCenterInsightsClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$contactCenterInsightsClient = new ContactCenterInsightsClient(); + +// Prepare the request message. +$conversation = new Conversation(); +$request = (new UpdateConversationRequest()) + ->setConversation($conversation); + +// Call the API and handle any network failures. +try { + /** @var Conversation $response */ + $response = $contactCenterInsightsClient->updateConversation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $contactCenterInsightsClient->updateConversation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateConversationRequest::build($conversation, $updateMask); +$response = $contactCenterInsightsClient->updateConversation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Container/MIGRATING.md b/Container/MIGRATING.md new file mode 100644 index 000000000000..4febf32e021b --- /dev/null +++ b/Container/MIGRATING.md @@ -0,0 +1,143 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Container\V1\Client\ClusterManagerClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Container\V1\ClusterManagerClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$clusterManagerClient = new ClusterManagerClient(); + +// Prepare the request message. +$request = new CancelOperationRequest(); + +// Call the API and handle any network failures. +try { + $clusterManagerClient->cancelOperation($request); + printf('Call completed successfully.' . PHP_EOL); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$clusterManagerClient->cancelOperation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = CancelOperationRequest::build($projectId, $zone, $operationId); +$clusterManagerClient->cancelOperation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/DataCatalog/MIGRATING.md b/DataCatalog/MIGRATING.md new file mode 100644 index 000000000000..408d99bc5fb5 --- /dev/null +++ b/DataCatalog/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\DataCatalog\V1\Client\DataCatalogClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\DataCatalog\V1\DataCatalogClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$dataCatalogClient = new DataCatalogClient(); + +// Prepare the request message. +$request = new LookupEntryRequest(); + +// Call the API and handle any network failures. +try { + /** @var Entry $response */ + $response = $dataCatalogClient->lookupEntry($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $dataCatalogClient->lookupEntry($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = CancelOperationRequest::build($projectId, $zone, $operationId); +$response = $dataCatalogClient->lookupEntry($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Datastream/MIGRATING.md b/Datastream/MIGRATING.md new file mode 100644 index 000000000000..d63b002fa843 --- /dev/null +++ b/Datastream/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Datastream\V1\Client\DatastreamClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Datastream\V1\DatastreamClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$datastreamClient = new DatastreamClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $datastreamClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $datastreamClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = CancelOperationRequest::build($projectId, $zone, $operationId); +$response = $datastreamClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Dms/MIGRATING.md b/Dms/MIGRATING.md new file mode 100644 index 000000000000..085fe3417fef --- /dev/null +++ b/Dms/MIGRATING.md @@ -0,0 +1,154 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\CloudDms\V1\Client\DataMigrationServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\CloudDms\V1\DataMigrationServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$dataMigrationServiceClient = new DataMigrationServiceClient(); + +// Prepare the request message. +$request = new ConvertConversionWorkspaceRequest(); + +// Call the API and handle any network failures. +try { + /** @var OperationResponse $response */ + $response = $dataMigrationServiceClient->convertConversionWorkspace($request); + $response->pollUntilComplete(); + + if ($response->operationSucceeded()) { + /** @var ConversionWorkspace $result */ + $result = $response->getResult(); + printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString()); + } else { + /** @var Status $error */ + $error = $response->getError(); + printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $dataMigrationServiceClient->convertConversionWorkspace($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = CancelOperationRequest::build($projectId, $zone, $operationId); +$response = $dataMigrationServiceClient->convertConversionWorkspace($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Eventarc/MIGRATING.md b/Eventarc/MIGRATING.md new file mode 100644 index 000000000000..fc17e386072f --- /dev/null +++ b/Eventarc/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Eventarc\V1\Client\EventarcClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Eventarc\V1\EventarcClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$eventarcClient = new EventarcClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $eventarcClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $eventarcClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = CancelOperationRequest::build($projectId, $zone, $operationId); +$response = $eventarcClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Filestore/MIGRATING.md b/Filestore/MIGRATING.md new file mode 100644 index 000000000000..72ea931d8490 --- /dev/null +++ b/Filestore/MIGRATING.md @@ -0,0 +1,154 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Filestore\V1\Client\CloudFilestoreManagerClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Filestore\V1\CloudFilestoreManagerClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$cloudFilestoreManagerClient = new CloudFilestoreManagerClient(); + +// Prepare the request message. +$request = new UpdateInstanceRequest(); + +// Call the API and handle any network failures. +try { + /** @var OperationResponse $response */ + $response = $cloudFilestoreManagerClient->updateInstance($request); + $response->pollUntilComplete(); + + if ($response->operationSucceeded()) { + /** @var Instance $result */ + $result = $response->getResult(); + printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString()); + } else { + /** @var Status $error */ + $error = $response->getError(); + printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $cloudFilestoreManagerClient->updateInstance($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateInstanceRequest::build($instance, $updateMask); +$response = $cloudFilestoreManagerClient->updateInstance($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/IamCredentials/MIGRATING.md b/IamCredentials/MIGRATING.md new file mode 100644 index 000000000000..a2521fff0fd9 --- /dev/null +++ b/IamCredentials/MIGRATING.md @@ -0,0 +1,146 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Iam\Credentials\V1\Client\IAMCredentialsClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Iam\Credentials\V1\IAMCredentialsClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$iAMCredentialsClient = new IAMCredentialsClient(); + +// Prepare the request message. +$request = (new SignBlobRequest()) + ->setName($formattedName) + ->setPayload($payload); + +// Call the API and handle any network failures. +try { + /** @var SignBlobResponse $response */ + $response = $iAMCredentialsClient->signBlob($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $iAMCredentialsClient->signBlob($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = SignBlobRequest::build($name, $delegates, $payload); +$response = $iAMCredentialsClient->signBlob($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Iap/MIGRATING.md b/Iap/MIGRATING.md new file mode 100644 index 000000000000..ec241164d54c --- /dev/null +++ b/Iap/MIGRATING.md @@ -0,0 +1,145 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Iap\V1\Client\IdentityAwareProxyOAuthServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Iap\V1\IdentityAwareProxyOAuthServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$identityAwareProxyOAuthServiceClient = new IdentityAwareProxyOAuthServiceClient(); + +// Prepare the request message. +$request = (new GetBrandRequest()) + ->setName($name); + +// Call the API and handle any network failures. +try { + /** @var Brand $response */ + $response = $identityAwareProxyOAuthServiceClient->getBrand($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $identityAwareProxyOAuthServiceClient->getBrand($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = SignBlobRequest::build($name, $delegates, $payload); +$response = $identityAwareProxyOAuthServiceClient->getBrand($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ManagedIdentities/MIGRATING.md b/ManagedIdentities/MIGRATING.md new file mode 100644 index 000000000000..355865257aac --- /dev/null +++ b/ManagedIdentities/MIGRATING.md @@ -0,0 +1,145 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ManagedIdentities\V1\Client\ManagedIdentitiesServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ManagedIdentities\V1\ManagedIdentitiesServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$managedIdentitiesServiceClient = new ManagedIdentitiesServiceClient(); + +// Prepare the request message. +$request = (new GetDomainRequest()) + ->setName($formattedName); + +// Call the API and handle any network failures. +try { + /** @var Domain $response */ + $response = $managedIdentitiesServiceClient->getDomain($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $managedIdentitiesServiceClient->getDomain($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = GetDomainRequest::build($name); +$response = $managedIdentitiesServiceClient->getDomain($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Memcache/MIGRATING.md b/Memcache/MIGRATING.md new file mode 100644 index 000000000000..726ba321a404 --- /dev/null +++ b/Memcache/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Memcache\V1\Client\CloudMemcacheClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Memcache\V1\CloudMemcacheClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$cloudMemcacheClient = new CloudMemcacheClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $cloudMemcacheClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $cloudMemcacheClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = GetDomainRequest::build($name); +$response = $cloudMemcacheClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/NetworkConnectivity/MIGRATING.md b/NetworkConnectivity/MIGRATING.md new file mode 100644 index 000000000000..d8019fa7ef21 --- /dev/null +++ b/NetworkConnectivity/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\NetworkConnectivity\V1\Client\PolicyBasedRoutingServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\NetworkConnectivity\V1\PolicyBasedRoutingServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$policyBasedRoutingServiceClient = new PolicyBasedRoutingServiceClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $policyBasedRoutingServiceClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $policyBasedRoutingServiceClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = GetDomainRequest::build($name); +$response = $policyBasedRoutingServiceClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/NetworkManagement/MIGRATING.md b/NetworkManagement/MIGRATING.md new file mode 100644 index 000000000000..ab3b527b811d --- /dev/null +++ b/NetworkManagement/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\NetworkManagement\V1\Client\ReachabilityServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\NetworkManagement\V1\ReachabilityServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$reachabilityServiceClient = new ReachabilityServiceClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $reachabilityServiceClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $reachabilityServiceClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = GetDomainRequest::build($name); +$response = $reachabilityServiceClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/OrchestrationAirflow/MIGRATING.md b/OrchestrationAirflow/MIGRATING.md new file mode 100644 index 000000000000..65d6635fe903 --- /dev/null +++ b/OrchestrationAirflow/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Orchestration\Airflow\Service\V1\Client\ImageVersionsClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Orchestration\Airflow\Service\V1\ImageVersionsClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$imageVersionsClient = new ImageVersionsClient(); + +// Prepare the request message. +$request = new ListImageVersionsRequest(); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $imageVersionsClient->listImageVersions($request); + + /** @var ImageVersion $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $imageVersionsClient->listImageVersions($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListImageVersionsRequest::build($parent); +$response = $imageVersionsClient->listImageVersions($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/OsLogin/MIGRATING.md b/OsLogin/MIGRATING.md new file mode 100644 index 000000000000..9f440d46e723 --- /dev/null +++ b/OsLogin/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\OsLogin\V1\Client\OsLoginServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\OsLogin\V1\OsLoginServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$osLoginServiceClient = new OsLoginServiceClient(); + +// Prepare the request message. +$request = (new DeletePosixAccountRequest()) + ->setName($formattedName); + +// Call the API and handle any network failures. +try { + $osLoginServiceClient->deletePosixAccount($request); + printf('Call completed successfully.' . PHP_EOL); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$osLoginServiceClient->deletePosixAccount($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = DeletePosixAccountRequest::build($name); +$osLoginServiceClient->deletePosixAccount($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/PolicyTroubleshooter/MIGRATING.md b/PolicyTroubleshooter/MIGRATING.md new file mode 100644 index 000000000000..94b254d915f6 --- /dev/null +++ b/PolicyTroubleshooter/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\PolicyTroubleshooter\V1\Client\IamCheckerClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\PolicyTroubleshooter\V1\IamCheckerClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$iamCheckerClient = new IamCheckerClient(); + +// Prepare the request message. +$request = new TroubleshootIamPolicyRequest(); + +// Call the API and handle any network failures. +try { + /** @var TroubleshootIamPolicyResponse $response */ + $response = $iamCheckerClient->troubleshootIamPolicy($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $iamCheckerClient->troubleshootIamPolicy($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = DeletePosixAccountRequest::build($name); +$response = $iamCheckerClient->troubleshootIamPolicy($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Profiler/MIGRATING.md b/Profiler/MIGRATING.md new file mode 100644 index 000000000000..4c4cd4e388a6 --- /dev/null +++ b/Profiler/MIGRATING.md @@ -0,0 +1,149 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Profiler\V2\Client\ExportServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Profiler\V2\ExportServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$exportServiceClient = new ExportServiceClient(); + +// Prepare the request message. +$request = (new ListProfilesRequest()) + ->setParent($formattedParent); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $exportServiceClient->listProfiles($request); + + /** @var Profile $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $exportServiceClient->listProfiles($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListProfilesRequest::build($parent); +$response = $exportServiceClient->listProfiles($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Recommender/MIGRATING.md b/Recommender/MIGRATING.md new file mode 100644 index 000000000000..eb883ffb5d58 --- /dev/null +++ b/Recommender/MIGRATING.md @@ -0,0 +1,146 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Recommender\V1\Client\RecommenderClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Recommender\V1\RecommenderClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$recommenderClient = new RecommenderClient(); + +// Prepare the request message. +$insightTypeConfig = new InsightTypeConfig(); +$request = (new UpdateInsightTypeConfigRequest()) + ->setInsightTypeConfig($insightTypeConfig); + +// Call the API and handle any network failures. +try { + /** @var InsightTypeConfig $response */ + $response = $recommenderClient->updateInsightTypeConfig($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $recommenderClient->updateInsightTypeConfig($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateInsightTypeConfigRequest::build($insightTypeConfig, $updateMask); +$response = $recommenderClient->updateInsightTypeConfig($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Redis/MIGRATING.md b/Redis/MIGRATING.md new file mode 100644 index 000000000000..67581777ad90 --- /dev/null +++ b/Redis/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Redis\V1\Client\CloudRedisClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Redis\V1\CloudRedisClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$cloudRedisClient = new CloudRedisClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $cloudRedisClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $cloudRedisClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateInsightTypeConfigRequest::build($insightTypeConfig, $updateMask); +$response = $cloudRedisClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ResourceSettings/MIGRATING.md b/ResourceSettings/MIGRATING.md new file mode 100644 index 000000000000..12ba5fa20115 --- /dev/null +++ b/ResourceSettings/MIGRATING.md @@ -0,0 +1,146 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ResourceSettings\V1\Client\ResourceSettingsServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ResourceSettings\V1\ResourceSettingsServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$resourceSettingsServiceClient = new ResourceSettingsServiceClient(); + +// Prepare the request message. +$setting = new Setting(); +$request = (new UpdateSettingRequest()) + ->setSetting($setting); + +// Call the API and handle any network failures. +try { + /** @var Setting $response */ + $response = $resourceSettingsServiceClient->updateSetting($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $resourceSettingsServiceClient->updateSetting($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateInsightTypeConfigRequest::build($insightTypeConfig, $updateMask); +$response = $resourceSettingsServiceClient->updateSetting($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/SecurityCenter/MIGRATING.md b/SecurityCenter/MIGRATING.md new file mode 100644 index 000000000000..a99c3944754f --- /dev/null +++ b/SecurityCenter/MIGRATING.md @@ -0,0 +1,146 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\SecurityCenter\V2\Client\SecurityCenterClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\SecurityCenter\V2\SecurityCenterClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$securityCenterClient = new SecurityCenterClient(); + +// Prepare the request message. +$bigQueryExport = new BigQueryExport(); +$request = (new UpdateBigQueryExportRequest()) + ->setBigQueryExport($bigQueryExport); + +// Call the API and handle any network failures. +try { + /** @var BigQueryExport $response */ + $response = $securityCenterClient->updateBigQueryExport($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $securityCenterClient->updateBigQueryExport($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateBigQueryExportRequest::build($bigQueryExport, $updateMask); +$response = $securityCenterClient->updateBigQueryExport($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/SecurityPrivateCa/MIGRATING.md b/SecurityPrivateCa/MIGRATING.md new file mode 100644 index 000000000000..94ed2682a412 --- /dev/null +++ b/SecurityPrivateCa/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Security\PrivateCA\V1\Client\CertificateAuthorityServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Security\PrivateCA\V1\CertificateAuthorityServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$certificateAuthorityServiceClient = new CertificateAuthorityServiceClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $certificateAuthorityServiceClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $certificateAuthorityServiceClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateBigQueryExportRequest::build($bigQueryExport, $updateMask); +$response = $certificateAuthorityServiceClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ServiceControl/MIGRATING.md b/ServiceControl/MIGRATING.md new file mode 100644 index 000000000000..b7249c6d6051 --- /dev/null +++ b/ServiceControl/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ServiceControl\V1\Client\ServiceControllerClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ServiceControl\V1\ServiceControllerClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$serviceControllerClient = new ServiceControllerClient(); + +// Prepare the request message. +$request = new ReportRequest(); + +// Call the API and handle any network failures. +try { + /** @var ReportResponse $response */ + $response = $serviceControllerClient->report($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $serviceControllerClient->report($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateBigQueryExportRequest::build($bigQueryExport, $updateMask); +$response = $serviceControllerClient->report($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ServiceDirectory/MIGRATING.md b/ServiceDirectory/MIGRATING.md new file mode 100644 index 000000000000..f2c1a4696e8c --- /dev/null +++ b/ServiceDirectory/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ServiceDirectory\V1\Client\LookupServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ServiceDirectory\V1\LookupServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$lookupServiceClient = new LookupServiceClient(); + +// Prepare the request message. +$request = new GetLocationRequest(); + +// Call the API and handle any network failures. +try { + /** @var Location $response */ + $response = $lookupServiceClient->getLocation($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $lookupServiceClient->getLocation($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = UpdateBigQueryExportRequest::build($bigQueryExport, $updateMask); +$response = $lookupServiceClient->getLocation($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ServiceManagement/MIGRATING.md b/ServiceManagement/MIGRATING.md new file mode 100644 index 000000000000..b4195a3c851e --- /dev/null +++ b/ServiceManagement/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ServiceManagement\V1\Client\ServiceManagerClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ServiceManagement\V1\ServiceManagerClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$serviceManagerClient = new ServiceManagerClient(); + +// Prepare the request message. +$request = new ListServicesRequest(); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $serviceManagerClient->listServices($request); + + /** @var ManagedService $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $serviceManagerClient->listServices($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListServicesRequest::build($producerProjectId, $consumerId); +$response = $serviceManagerClient->listServices($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/ServiceUsage/MIGRATING.md b/ServiceUsage/MIGRATING.md new file mode 100644 index 000000000000..48d574086269 --- /dev/null +++ b/ServiceUsage/MIGRATING.md @@ -0,0 +1,144 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\ServiceUsage\V1\Client\ServiceUsageClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\ServiceUsage\V1\ServiceUsageClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$serviceUsageClient = new ServiceUsageClient(); + +// Prepare the request message. +$request = new GetServiceRequest(); + +// Call the API and handle any network failures. +try { + /** @var Service $response */ + $response = $serviceUsageClient->getService($request); + printf('Response data: %s' . PHP_EOL, $response->serializeToJsonString()); +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $serviceUsageClient->getService($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListServicesRequest::build($producerProjectId, $consumerId); +$response = $serviceUsageClient->getService($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/Shell/MIGRATING.md b/Shell/MIGRATING.md new file mode 100644 index 000000000000..9e7519879b9a --- /dev/null +++ b/Shell/MIGRATING.md @@ -0,0 +1,154 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Shell\V1\Client\CloudShellServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Shell\V1\CloudShellServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$cloudShellServiceClient = new CloudShellServiceClient(); + +// Prepare the request message. +$request = new AddPublicKeyRequest(); + +// Call the API and handle any network failures. +try { + /** @var OperationResponse $response */ + $response = $cloudShellServiceClient->addPublicKey($request); + $response->pollUntilComplete(); + + if ($response->operationSucceeded()) { + /** @var AddPublicKeyResponse $result */ + $result = $response->getResult(); + printf('Operation successful with response data: %s' . PHP_EOL, $result->serializeToJsonString()); + } else { + /** @var Status $error */ + $error = $response->getError(); + printf('Operation failed with error data: %s' . PHP_EOL, $error->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $cloudShellServiceClient->addPublicKey($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListServicesRequest::build($producerProjectId, $consumerId); +$response = $cloudShellServiceClient->addPublicKey($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/VpcAccess/MIGRATING.md b/VpcAccess/MIGRATING.md new file mode 100644 index 000000000000..a01861abdfe5 --- /dev/null +++ b/VpcAccess/MIGRATING.md @@ -0,0 +1,148 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\VpcAccess\V1\Client\VpcAccessServiceClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\VpcAccess\V1\VpcAccessServiceClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// Create a client. +$vpcAccessServiceClient = new VpcAccessServiceClient(); + +// Prepare the request message. +$request = new ListLocationsRequest(); + +// Call the API and handle any network failures. +try { + /** @var PagedListResponse $response */ + $response = $vpcAccessServiceClient->listLocations($request); + + /** @var Location $element */ + foreach ($response as $element) { + printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString()); + } +} catch (ApiException $ex) { + printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage()); +} +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $vpcAccessServiceClient->listLocations($request, $callOptions); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +// Create the RPC request using the static "::build" method +$request = ListServicesRequest::build($producerProjectId, $consumerId); +$response = $vpcAccessServiceClient->listLocations($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/dev/src/Command/DocFxCommand.php b/dev/src/Command/DocFxCommand.php index fb9149ba6f87..74de50b014fc 100644 --- a/dev/src/Command/DocFxCommand.php +++ b/dev/src/Command/DocFxCommand.php @@ -139,6 +139,16 @@ protected function execute(InputInterface $input, OutputInterface $output) } if (file_exists($overviewFile = sprintf('%s/README.md', $component->getPath()))) { + // Add Migrating Doc if we are in a V2 component + if (str_starts_with($component->getPackageVersion(), '2.')) { + if (!file_exists($migratingFile = sprintf($component->getPath() . '/MIGRATING.md'))) { + $migratingFile = Component::ROOT_DIR . '/MIGRATING.md'; + } + file_put_contents($outDir . '/migrating.md', file_get_contents($migratingFile)); + // Add "migrating" as the second item on the TOC (after "overview") + array_unshift($tocItems, ['name' => 'Migrating', 'href' => 'migrating.md']); + } + $overview = new OverviewPage( file_get_contents($overviewFile), $isBeta diff --git a/dev/src/Component.php b/dev/src/Component.php index feb9cac32914..c8d8afb8c801 100644 --- a/dev/src/Component.php +++ b/dev/src/Component.php @@ -28,7 +28,7 @@ class Component { const VERSION_REGEX = '/^V([0-9])?(p[0-9])?(beta|alpha)?[0-9]?$/'; - private const ROOT_DIR = __DIR__ . '/../../'; + public const ROOT_DIR = __DIR__ . '/../../'; private string $path; private string $releaseLevel; private string $packageName; diff --git a/dev/tests/Unit/Command/DocFxCommandTest.php b/dev/tests/Unit/Command/DocFxCommandTest.php index 3b7025aa939a..a4d99c0f05b0 100644 --- a/dev/tests/Unit/Command/DocFxCommandTest.php +++ b/dev/tests/Unit/Command/DocFxCommandTest.php @@ -107,7 +107,7 @@ public function testDocFxFiles(string $file) { $this->assertTrue( file_exists(self::$fixturesDir . '/docfx/Vision/' . $file), - sprintf('tests/fixtures/docfx/%s does not exist (%s)', $file, self::$tmpDir . '/' . $file) + sprintf(self::$fixturesDir . '/docfx/Vision/%s does not exist (%s)', $file, self::$tmpDir . '/' . $file) ); $left = self::$fixturesDir . '/docfx/Vision/' . $file; diff --git a/dev/tests/fixtures/component/Vision/VERSION b/dev/tests/fixtures/component/Vision/VERSION new file mode 100644 index 000000000000..2165f8f9b6a8 --- /dev/null +++ b/dev/tests/fixtures/component/Vision/VERSION @@ -0,0 +1 @@ +2.0.4 diff --git a/dev/tests/fixtures/docfx/Vision/migrating.md b/dev/tests/fixtures/docfx/Vision/migrating.md new file mode 100644 index 000000000000..e6a80d2a186a --- /dev/null +++ b/dev/tests/fixtures/docfx/Vision/migrating.md @@ -0,0 +1,165 @@ +# Migrating Google Cloud Clients to the New Surface + +**Document Summary** + + * Google Cloud PHP Client Libraries are releasing new major versions (v2) to + introduce new surface changes. + * The PHP Team at Google has developed a tool to automatically upgrade clients + (see [`ClientUpgradeFixer`][client_upgrade_fixer]). + +## WHAT are the new Cloud Clients? + +The new Cloud Clients are in the namespace `\Client\`, whereas the previous +clients are one directory above with the same name. For example: + +```php +// This is the "new" client +use Google\Cloud\Tasks\V2\Client\CloudTasksClient; + +// This is the deprecated client (marked with @deprecated) +use Google\Cloud\Tasks\V2\CloudTasksClient; +``` + +The main difference is that RPC methods which used to take a varying number of +required arguments plus an array of optional arguments, now only take a +_single_ `Request` object: + +```php +// The NEW surface client +use Google\Cloud\Tasks\V2\Client\CloudTasksClient; +// The Request class required to make the RPC +use Google\Cloud\Tasks\V2\CreateTaskRequest; +// Messages used to build the request +use Google\Cloud\Tasks\V2\Task; + +$parent = CloudTasksClient::queueName('[PROJECT]', '[LOCATION]', '[QUEUE]'); +$task = new Task(); + +// This is the NEW way to make an RPC request +$tasksClient = new CloudTasksClient(); +$request = (new CreateTaskRequest()) + ->setParent($parent) + ->setTask($task) + ->setResponseView(Task\View::FULL); +$response = $taskClient->createTask($request); + +// This is the DEPRECATED way to make the same RPC request +use Google\Cloud\Tasks\V2\CloudTasksClient as DeprecatedCloudTasksClient; + +$tasksClient = new DeprecatedCloudTasksClient(); +$response = $taskClient->createTask($parent, $task, [ + 'responseView' => Task\View::FULL, +]); +``` + +### RPCs use CallOptions + +The new surface RPC methods take an optional array of +[CallOptions][call_options] as the second argument. These are similar to how +the `$optionalArgs` were used in the previous surface, but the new `CallOptions` +_only_ contain options for the call itself, whereas the previous `$optionalArgs` +also held the optional fields for the request body: + +```php +// To set call-time options, such as headers, timeouts, and retry options, +// pass them in as the second argument +$callOptions = ['timeoutMillis' => 20]; +$response = $taskClient->createTask($request, $callOptions); + +// This is the DEPRECATED way to make the same RPC request +$response = $taskClient->createTask($parent, $task, [ + 'responseView' => Task\View::FULL, + 'timeoutMillis' => 20, +]); +``` + +[call_options]: https://github.com/googleapis/gax-php/blob/main/src/Options/CallOptions.php + +### Requests have static `::build` methods + +Using Request objects directly can make it more difficult to quickly draft out +the necessary code to deliver an RPC. To mitigate this friction, a static +`::build` method is now generated when one or more +[method signature annotations](https://google.aip.dev/client-libraries/4232) +exist on the RPC. + +Any request which has recommended parameters defined in its proto will include a +`::build` method, so that these parameters are easily discoverable: + +```php +$tasksClient = new CloudTasksClient(); +$parent = CloudTasksClient::queueName('[PROJECT]', '[LOCATION]', '[QUEUE]'); +$task = new Task(); + +// Create the RPC request using the static "::build" method +$request = CreateTaskRequest::build($parent, $task); +$response = $taskClient->createTask($request); +``` + +## HOW should I upgrade? + +The changes are mostly straightforward, and at a minimum require the following: + + - Update Google Cloud clients to use the new client namespace by appending + `\Client` to the existing namespace. + - Update RPC calls to accept the corresponding `Request` object. + +**NOTE**: Client streaming calls do not require a `Request` object. + +### Automatically upgrade code using the `ClientUpgradeFixer` tool + +To help migrate code to the new client surface, we've written a +[ClientUpgradeFixer][client_upgrade_fixer] to scan code and upgrade it to match +the new client surface. This tool is not guaranteed to work, so be sure to test +everything that it changes thoroughly. Read more about how to install and run +the tool in its [README][client_upgrade_fixer]. + +The ClientUpgradeFixer uses [PHP Coding Standards Fixer][cs_fixer] to upgrade +code to use the new client surface: + +```bash +# run the CS fixer for that directory using the config above +vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.google.php --dry-run --diff /path/to/my/project +``` + +This will output a diff of the changes. Remove `--dry-run` from the above +command to apply the changes automatically. + + +```diff +-use Google\Cloud\Dlp\V2\DlpServiceClient; ++use Google\Cloud\Dlp\V2\Client\DlpServiceClient; ++use Google\Cloud\Dlp\V2\CreateDlpJobRequest; + use Google\Cloud\Dlp\V2\InspectConfig; + use Google\Cloud\Dlp\V2\InspectJobConfig; + use Google\Cloud\Dlp\V2\Likelihood; ++use Google\Cloud\Dlp\V2\ListInfoTypesRequest; + use Google\Cloud\Dlp\V2\StorageConfig; + + // Instantiate a client. + $dlp = new DlpServiceClient(); + + // optional args array (variable) +-$infoTypes = $dlp->listInfoTypes($parent); ++$request = (new ListInfoTypesRequest()); ++$infoTypes = $dlp->listInfoTypes($request); + + // optional args array (inline array) +-$job = $dlp->createDlpJob($parent, ['jobId' => 'abc', 'locationId' => 'def']); ++$request2 = (new CreateDlpJobRequest()) ++ ->setParent($parent) ++ ->setJobId('abc') ++ ->setLocationId('def'); ++$job = $dlp->createDlpJob($request2); +``` + +[cs_fixer]: https://cs.symfony.com/ +[client_upgrade_fixer]: https://github.com/GoogleCloudPlatform/php-tools/blob/main/src/Fixers/ClientUpgradeFixer/README.md + +## Feedback + +Your feedback is important to us! Please continue to provide us with any +thoughts and questions in the [Issues][google-cloud-issues] section of this +repository. + +[google-cloud-issues]: https://github.com/googleapis/google-cloud-php/issues diff --git a/dev/tests/fixtures/docfx/Vision/toc.yml b/dev/tests/fixtures/docfx/Vision/toc.yml index 82cd4b15169d..7c4cf2f1169f 100644 --- a/dev/tests/fixtures/docfx/Vision/toc.yml +++ b/dev/tests/fixtures/docfx/Vision/toc.yml @@ -5,6 +5,9 @@ - name: Overview href: index.md + - + name: Migrating + href: migrating.md - name: V1 uid: 'ns:Google\Cloud\Vision\V1'