diff --git a/AutoMl/MIGRATING.md b/AutoMl/MIGRATING.md
new file mode 100644
index 000000000000..0c2a6ed56dc6
--- /dev/null
+++ b/AutoMl/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\AutoMl\V1\Client\AutoMlClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\AutoMl\V1\AutoMlClient;
+```
+
+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.
+$autoMlClient = new AutoMlClient();
+
+// Prepare the request message.
+$dataset = new Dataset();
+$updateMask = new FieldMask();
+$request = (new UpdateDatasetRequest())
+    ->setDataset($dataset)
+    ->setUpdateMask($updateMask);
+
+// Call the API and handle any network failures.
+try {
+    /** @var Dataset $response */
+    $response = $autoMlClient->updateDataset($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 = $autoMlClient->updateDataset($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 = UpdateDatasetRequest::build($dataset, $updateMask);
+$response = $autoMlClient->updateDataset($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/BigQueryDataTransfer/MIGRATING.md b/BigQueryDataTransfer/MIGRATING.md
new file mode 100644
index 000000000000..b7b58c7be95d
--- /dev/null
+++ b/BigQueryDataTransfer/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\DataTransfer\V1\Client\DataTransferServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\BigQuery\DataTransfer\V1\DataTransferServiceClient;
+```
+
+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.
+$dataTransferServiceClient = new DataTransferServiceClient();
+
+// Prepare the request message.
+$request = new GetLocationRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var Location $response */
+    $response = $dataTransferServiceClient->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 = $dataTransferServiceClient->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 = UpdateDatasetRequest::build($dataset, $updateMask);
+$response = $dataTransferServiceClient->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/Dataproc/MIGRATING.md b/Dataproc/MIGRATING.md
new file mode 100644
index 000000000000..b1366dc90c98
--- /dev/null
+++ b/Dataproc/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\Dataproc\V1\Client\SessionControllerClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Dataproc\V1\SessionControllerClient;
+```
+
+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.
+$sessionControllerClient = new SessionControllerClient();
+
+// Prepare the request message.
+$request = (new GetSessionRequest())
+    ->setName($formattedName);
+
+// Call the API and handle any network failures.
+try {
+    /** @var Session $response */
+    $response = $sessionControllerClient->getSession($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 = $sessionControllerClient->getSession($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 = GetSessionRequest::build($name);
+$response = $sessionControllerClient->getSession($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/Dlp/MIGRATING.md b/Dlp/MIGRATING.md
new file mode 100644
index 000000000000..11ddb85578df
--- /dev/null
+++ b/Dlp/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\Dlp\V2\Client\DlpServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Dlp\V2\DlpServiceClient;
+```
+
+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.
+$dlpServiceClient = new DlpServiceClient();
+
+// Prepare the request message.
+$request = new ListInfoTypesRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var ListInfoTypesResponse $response */
+    $response = $dlpServiceClient->listInfoTypes($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 = $dlpServiceClient->listInfoTypes($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 = ListInfoTypesRequest::build($parent);
+$response = $dlpServiceClient->listInfoTypes($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/DocumentAi/MIGRATING.md b/DocumentAi/MIGRATING.md
new file mode 100644
index 000000000000..5016de0f01aa
--- /dev/null
+++ b/DocumentAi/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\DocumentAI\V1\Client\DocumentProcessorServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\DocumentAI\V1\DocumentProcessorServiceClient;
+```
+
+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.
+$documentProcessorServiceClient = new DocumentProcessorServiceClient();
+
+// Prepare the request message.
+$request = new GetLocationRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var Location $response */
+    $response = $documentProcessorServiceClient->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 = $documentProcessorServiceClient->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 = ListInfoTypesRequest::build($parent);
+$response = $documentProcessorServiceClient->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/Functions/MIGRATING.md b/Functions/MIGRATING.md
new file mode 100644
index 000000000000..1b23cc62e59b
--- /dev/null
+++ b/Functions/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\Functions\V2\Client\FunctionServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Functions\V2\FunctionServiceClient;
+```
+
+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.
+$functionServiceClient = new FunctionServiceClient();
+
+// Prepare the request message.
+$request = new ListLocationsRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var PagedListResponse $response */
+    $response = $functionServiceClient->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 = $functionServiceClient->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 = ListInfoTypesRequest::build($parent);
+$response = $functionServiceClient->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/Kms/MIGRATING.md b/Kms/MIGRATING.md
new file mode 100644
index 000000000000..87766ea30120
--- /dev/null
+++ b/Kms/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\Kms\V1\Client\KeyManagementServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Kms\V1\KeyManagementServiceClient;
+```
+
+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.
+$keyManagementServiceClient = new KeyManagementServiceClient();
+
+// Prepare the request message.
+$request = new GetLocationRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var Location $response */
+    $response = $keyManagementServiceClient->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 = $keyManagementServiceClient->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 = ListInfoTypesRequest::build($parent);
+$response = $keyManagementServiceClient->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/OsConfig/MIGRATING.md b/OsConfig/MIGRATING.md
new file mode 100644
index 000000000000..8fd8ebbae62e
--- /dev/null
+++ b/OsConfig/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\OsConfig\V1\Client\OsConfigZonalServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\OsConfig\V1\OsConfigZonalServiceClient;
+```
+
+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.
+$osConfigZonalServiceClient = new OsConfigZonalServiceClient();
+
+// Prepare the request message.
+$request = (new ListOSPolicyAssignmentsRequest())
+    ->setParent($formattedParent);
+
+// Call the API and handle any network failures.
+try {
+    /** @var PagedListResponse $response */
+    $response = $osConfigZonalServiceClient->listOSPolicyAssignments($request);
+
+    /** @var OSPolicyAssignment $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 = $osConfigZonalServiceClient->listOSPolicyAssignments($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 = ListOSPolicyAssignmentsRequest::build($parent);
+$response = $osConfigZonalServiceClient->listOSPolicyAssignments($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/Retail/MIGRATING.md b/Retail/MIGRATING.md
new file mode 100644
index 000000000000..3938dcba5c56
--- /dev/null
+++ b/Retail/MIGRATING.md
@@ -0,0 +1,150 @@
+# 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\Retail\V2\Client\SearchServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Retail\V2\SearchServiceClient;
+```
+
+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.
+$searchServiceClient = new SearchServiceClient();
+
+// Prepare the request message.
+$request = (new SearchRequest())
+    ->setPlacement($placement)
+    ->setVisitorId($visitorId);
+
+// Call the API and handle any network failures.
+try {
+    /** @var PagedListResponse $response */
+    $response = $searchServiceClient->search($request);
+
+    /** @var SearchResult $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 = $searchServiceClient->search($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 = ListOSPolicyAssignmentsRequest::build($parent);
+$response = $searchServiceClient->search($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/Scheduler/MIGRATING.md b/Scheduler/MIGRATING.md
new file mode 100644
index 000000000000..478d1ce2e026
--- /dev/null
+++ b/Scheduler/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\Scheduler\V1\Client\CloudSchedulerClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Scheduler\V1\CloudSchedulerClient;
+```
+
+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.
+$cloudSchedulerClient = new CloudSchedulerClient();
+
+// Prepare the request message.
+$request = new GetLocationRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var Location $response */
+    $response = $cloudSchedulerClient->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 = $cloudSchedulerClient->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 = ListOSPolicyAssignmentsRequest::build($parent);
+$response = $cloudSchedulerClient->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/StorageTransfer/MIGRATING.md b/StorageTransfer/MIGRATING.md
new file mode 100644
index 000000000000..b466502ffa93
--- /dev/null
+++ b/StorageTransfer/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\StorageTransfer\V1\Client\StorageTransferServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\StorageTransfer\V1\StorageTransferServiceClient;
+```
+
+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.
+$storageTransferServiceClient = new StorageTransferServiceClient();
+
+// Prepare the request message.
+$transferJob = new TransferJob();
+$request = (new CreateTransferJobRequest())
+    ->setTransferJob($transferJob);
+
+// Call the API and handle any network failures.
+try {
+    /** @var TransferJob $response */
+    $response = $storageTransferServiceClient->createTransferJob($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 = $storageTransferServiceClient->createTransferJob($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 = ListOSPolicyAssignmentsRequest::build($parent);
+$response = $storageTransferServiceClient->createTransferJob($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/Talent/MIGRATING.md b/Talent/MIGRATING.md
new file mode 100644
index 000000000000..d6093d462032
--- /dev/null
+++ b/Talent/MIGRATING.md
@@ -0,0 +1,147 @@
+# 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\Talent\V4\Client\CompletionClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\Talent\V4\CompletionClient;
+```
+
+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.
+$completionClient = new CompletionClient();
+
+// Prepare the request message.
+$request = (new CompleteQueryRequest())
+    ->setTenant($formattedTenant)
+    ->setQuery($query)
+    ->setPageSize($pageSize);
+
+// Call the API and handle any network failures.
+try {
+    /** @var CompleteQueryResponse $response */
+    $response = $completionClient->completeQuery($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 = $completionClient->completeQuery($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 = ListOSPolicyAssignmentsRequest::build($parent);
+$response = $completionClient->completeQuery($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/VideoIntelligence/MIGRATING.md b/VideoIntelligence/MIGRATING.md
new file mode 100644
index 000000000000..b28621201106
--- /dev/null
+++ b/VideoIntelligence/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\VideoIntelligence\V1\Client\VideoIntelligenceServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\VideoIntelligence\V1\VideoIntelligenceServiceClient;
+```
+
+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.
+$videoIntelligenceServiceClient = new VideoIntelligenceServiceClient();
+
+// Prepare the request message.
+$request = new AnnotateVideoRequest();
+
+// Call the API and handle any network failures.
+try {
+    /** @var OperationResponse $response */
+    $response = $videoIntelligenceServiceClient->annotateVideo($request);
+    $response->pollUntilComplete();
+
+    if ($response->operationSucceeded()) {
+        /** @var AnnotateVideoResponse $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 = $videoIntelligenceServiceClient->annotateVideo($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 = AnnotateVideoRequest::build($inputUri, $features);
+$response = $videoIntelligenceServiceClient->annotateVideo($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/WebRisk/MIGRATING.md b/WebRisk/MIGRATING.md
new file mode 100644
index 000000000000..afa4a879e485
--- /dev/null
+++ b/WebRisk/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\WebRisk\V1\Client\WebRiskServiceClient;
+
+// This is the deprecated client (marked with @deprecated)
+use Google\Cloud\WebRisk\V1\WebRiskServiceClient;
+```
+
+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.
+$webRiskServiceClient = new WebRiskServiceClient();
+
+// Prepare the request message.
+$threatTypes = [$threatTypesElement,];
+$request = (new SearchHashesRequest())
+    ->setThreatTypes($threatTypes);
+
+// Call the API and handle any network failures.
+try {
+    /** @var SearchHashesResponse $response */
+    $response = $webRiskServiceClient->searchHashes($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 = $webRiskServiceClient->searchHashes($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 = SearchHashesRequest::build($hashPrefix, $threatTypes);
+$response = $webRiskServiceClient->searchHashes($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