From c591bb3550f8d022bc7f5e75a5d0af8589718ffe Mon Sep 17 00:00:00 2001 From: Brent Shaffer Date: Thu, 12 Nov 2026 18:25:28 +0000 Subject: [PATCH 1/5] docs: add ASYNC.md product-neutral guide for Promises and PHP Fibers --- ASYNC.md | 277 +++++++++++++++++ README.md | 4 + dev/src/Command/DocFxCommand.php | 1 + .../ProductNeutralGuides/AsyncTest.php | 285 ++++++++++++++++++ .../docfx/ProductNeutralGuides/async.md | 277 +++++++++++++++++ .../ProductNeutralGuides/getting-started.md | 4 + .../docfx/ProductNeutralGuides/toc.yml | 3 + 7 files changed, 851 insertions(+) create mode 100644 ASYNC.md create mode 100644 dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php create mode 100644 dev/tests/fixtures/docfx/ProductNeutralGuides/async.md diff --git a/ASYNC.md b/ASYNC.md new file mode 100644 index 000000000000..0f8765342ac8 --- /dev/null +++ b/ASYNC.md @@ -0,0 +1,277 @@ +# Asynchronous Requests and Concurrency + +Every generated Google Cloud PHP V2 client (`*\Client\*Client`) provides an `*Async()` method alongside each synchronous RPC method—for example, `accessSecretVersionAsync()` alongside `accessSecretVersion()`. These methods return a [`GuzzleHttp\Promise\PromiseInterface`](https://github.com/guzzle/promises), allowing a single PHP process to execute multiple API calls concurrently over **both gRPC and REST**. + +* **gRPC (`'transport' => 'grpc'`, default when `ext-grpc` is installed):** Calling `*Async()` immediately dispatches the RPC onto the `grpc` C extension's background network threads over multiplexed HTTP/2 streams. +* **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. + +## 1. Concurrent Requests with Promises + +### Waiting on Multiple Requests (`Utils::unwrap`) + +Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` throws a `Google\ApiCore\ApiException` immediately. + +```php +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use GuzzleHttp\Promise\Utils; + +$client = new SecretManagerServiceClient([ + // Works with both 'grpc' (default) and 'rest' + 'transport' => 'grpc', +]); + +$secretIds = ['db-password', 'api-key', 'jwt-signing-key']; +$promises = []; + +foreach ($secretIds as $secretId) { + $versionName = SecretManagerServiceClient::secretVersionName( + 'my-project', + $secretId, + 'latest' + ); + $request = (new AccessSecretVersionRequest())->setName($versionName); + + // Starts the request without blocking + $promises[$secretId] = $client->accessSecretVersionAsync($request); +} + +// Wait for all in-flight requests to complete concurrently +$responses = Utils::unwrap($promises); + +foreach ($responses as $secretId => $response) { + printf("%s: %s\n", $secretId, $response->getPayload()->getData()); +} +``` + +### Handling Partial Failures (`Utils::settle`) + +When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or `PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. + +```php +use Google\ApiCore\ApiException; +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; + +$client = new SecretManagerServiceClient(); + +$promises = [ + 'existing' => $client->accessSecretVersionAsync( + (new AccessSecretVersionRequest())->setName( + SecretManagerServiceClient::secretVersionName('my-project', 'existing', 'latest') + ) + ), + 'missing' => $client->accessSecretVersionAsync( + (new AccessSecretVersionRequest())->setName( + SecretManagerServiceClient::secretVersionName('my-project', 'missing', 'latest') + ) + ), +]; + +$results = Utils::settle($promises)->wait(); + +foreach ($results as $key => $result) { + if ($result['state'] === PromiseInterface::FULFILLED) { + printf("%s succeeded: %s\n", $key, $result['value']->getPayload()->getData()); + } else { + /** @var ApiException $error */ + $error = $result['reason']; + printf("%s failed: %s\n", $key, $error->getStatus()); + } +} +``` + +### Limiting Concurrency (`EachPromise`) + +Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive concurrent streams or hits API rate limits. Yield promises lazily from a generator into `GuzzleHttp\Promise\EachPromise` with a fixed `concurrency` cap. + +```php +use Google\Cloud\PubSub\V1\Client\PublisherClient; +use Google\Cloud\PubSub\V1\PubsubMessage; +use Google\Cloud\PubSub\V1\PublishRequest; +use Google\Cloud\PubSub\V1\PublishResponse; +use GuzzleHttp\Promise\EachPromise; + +$publisher = new PublisherClient(); +$topicName = PublisherClient::topicName('my-project', 'my-topic'); +$payloads = ['event-1', 'event-2', 'event-3', 'event-4', 'event-5']; + +$promiseGenerator = (function () use ($publisher, $topicName, $payloads) { + foreach ($payloads as $payload) { + $request = (new PublishRequest()) + ->setTopic($topicName) + ->setMessages([ + (new PubsubMessage())->setData($payload), + ]); + + yield $payload => $publisher->publishAsync($request); + } +})(); + +$publishedCount = 0; +$eachPromise = new EachPromise($promiseGenerator, [ + // Keep at most 2 requests in flight at any time + 'concurrency' => 2, + 'fulfilled' => function (PublishResponse $response, string $payload) use (&$publishedCount) { + $publishedCount += count($response->getMessageIds()); + }, +]); + +$eachPromise->promise()->wait(); +printf("Published %d messages\n", $publishedCount); +``` + +## 2. Supported Call Types + +| Call Type | `*Async()` Return Type | Behavior | +| :--- | :--- | :--- | +| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | +| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `pageToken` explicitly to `*Async()`. | +| **Long-Running Operation (LRO)** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts](https://docs.cloud.google.com/php/docs/reference/help/core_concepts) for polling LROs. | +| **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | + +### Handwritten Client Helpers + +Most handwritten wrapper clients (`BigQueryClient`, `SpannerClient`, `FirestoreClient`) expose synchronous helper APIs; use the underlying generated `V1\Client\*Client` classes when you need `*Async()` methods. For Cloud Storage, `Google\Cloud\Storage\Bucket` and `StorageObject` provide `uploadAsync()` and `downloadAsStreamAsync()` directly: + +```php +use Google\Cloud\Storage\StorageClient; +use GuzzleHttp\Promise\Utils; + +$storage = new StorageClient(); +$bucket = $storage->bucket('my-bucket'); + +$files = [ + 'report-1.txt' => 'First report contents', + 'report-2.txt' => 'Second report contents', +]; + +$promises = []; +foreach ($files as $name => $contents) { + $promises[$name] = $bucket->uploadAsync($contents, ['name' => $name]); +} + +$objects = Utils::unwrap($promises); +foreach ($objects as $name => $object) { + printf("Uploaded %s\n", $object->name()); +} +``` + +## 3. Using PHP Fibers with the REST Transport + +PHP `Fiber`s allow you to write normal synchronous client code (such as `$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. + +Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's `CurlMultiHandler` (or an event loop like [`revolt/event-loop`](https://revolt.run/)) and pass a Fiber-aware `httpHandler` and `authHttpHandler` to the **`rest`** transport. + +> [!IMPORTANT] +> Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the `*Async()` methods shown in Section 1. + +### Driving Fibers with `CurlMultiHandler` + +The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. + +```php +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use GuzzleHttp\Client; +use GuzzleHttp\Handler\CurlMultiHandler; +use GuzzleHttp\HandlerStack; +use GuzzleHttp\Promise\Promise; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; +use Psr\Http\Message\RequestInterface; +use Psr\Http\Message\ResponseInterface; + +$curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); +$httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); + +// Suspends the current Fiber until Guzzle resolves the HTTP transfer +$asyncFiberHandler = function (RequestInterface $request, array $options = []) use ($httpClient): PromiseInterface { + $guzzlePromise = $httpClient->sendAsync($request, $options); + $fiber = Fiber::getCurrent(); + if ($fiber === null) { + return $guzzlePromise; + } + + return $promise = new Promise(function () use (&$promise, $guzzlePromise, $fiber) { + $guzzlePromise->then( + static fn () => $fiber->isSuspended() && $fiber->resume(), + static fn () => $fiber->isSuspended() && $fiber->resume() + ); + if ($guzzlePromise->getState() === PromiseInterface::PENDING) { + Fiber::suspend(); + } + try { + $promise->resolve($guzzlePromise->wait()); + } catch (\Throwable $e) { + $promise->reject($e); + } + }); +}; + +// Wraps the async handler for synchronous OAuth2 token fetches in google/auth +$syncFiberHandler = static fn (RequestInterface $request, array $options = []): ResponseInterface => + $asyncFiberHandler($request, $options)->wait(); + +$client = new SecretManagerServiceClient([ + 'transport' => 'rest', + 'credentialsConfig' => [ + 'authHttpHandler' => $syncFiberHandler, + ], + 'transportConfig' => [ + 'rest' => [ + 'httpHandler' => $asyncFiberHandler, + ], + ], +]); + +$secretIds = ['db-password', 'api-key', 'jwt-signing-key']; +$fibers = []; + +foreach ($secretIds as $secretId) { + $fiber = new Fiber(function () use ($client, $secretId): string { + $request = (new AccessSecretVersionRequest())->setName( + SecretManagerServiceClient::secretVersionName('my-project', $secretId, 'latest') + ); + + // Synchronous method call—suspends this Fiber while HTTP I/O is in flight + $response = $client->accessSecretVersion($request); + return $response->getPayload()->getData(); + }); + $fiber->start(); + $fibers[$secretId] = $fiber; +} + +// Tick Guzzle's curl_multi loop until all fibers complete +while (array_filter($fibers, static fn (Fiber $f) => !$f->isTerminated())) { + $curlMulti->tick(); + Utils::queue()->run(); +} + +foreach ($fibers as $secretId => $fiber) { + printf("%s: %s\n", $secretId, $fiber->getReturn()); +} +``` + +### Integrating with an Event Loop (`revolt/event-loop` / Amp) + +In long-running async applications built on [`revolt/event-loop`](https://revolt.run/) or [`amphp/amp`](https://amphp.org/), register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active instead of writing a manual `while` loop: + +```php +use Revolt\EventLoop; +use GuzzleHttp\Promise\Utils; + +// Register a periodic callback to advance cURL transfers on the Revolt loop +$timerId = EventLoop::repeat(0.01, static function () use ($curlMulti): void { + $curlMulti->tick(); + Utils::queue()->run(); +}); + +// Unreference the timer so it does not keep the process alive once work finishes +EventLoop::unreference($timerId); +``` + +> [!NOTE] +> Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread during backoff. In latency-sensitive event-loop servers, consider setting `'disableRetries' => true` on the client and handling retry delays with your event loop's non-blocking timer (such as `Amp\delay()`). diff --git a/README.md b/README.md index 657cb94804b4..d7111921f9d2 100644 --- a/README.md +++ b/README.md @@ -104,6 +104,10 @@ See [Authentication](AUTHENTICATION.md) for details and examples. Please see our [Debugging guide](DEBUG.md) for more information about the debugging tools. +## Asynchronous Requests + +Every generated V2 client exposes `*Async()` methods returning Guzzle Promises for concurrent requests over both gRPC and REST. See [Asynchronous Requests and Concurrency](ASYNC.md) for examples using Promises and PHP Fibers. + ## gRPC and Protobuf Many clients in Google Cloud PHP offer support for gRPC, either as an option or a requirement. gRPC diff --git a/dev/src/Command/DocFxCommand.php b/dev/src/Command/DocFxCommand.php index 9189a7744b59..eb900a56775a 100644 --- a/dev/src/Command/DocFxCommand.php +++ b/dev/src/Command/DocFxCommand.php @@ -57,6 +57,7 @@ class DocFxCommand extends Command 'AUTHENTICATION.md' => 'Authentication', 'CORE_CONCEPTS.md' => 'Core Concepts', 'CLIENT_CONFIGURATION.md' => 'Client Configuration', + 'ASYNC.md' => 'Asynchronous Requests', 'OCC_FOR_IAM.md' => 'OCC for IAM', 'MIGRATING.md' => 'Migrating to V2', 'GRPC.md' => 'Installing gRPC and Protobuf', diff --git a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php new file mode 100644 index 000000000000..2b0f0ddfafaf --- /dev/null +++ b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php @@ -0,0 +1,285 @@ +snippetFromMarkdown( + self::ASYNC_FILE, + 'Waiting on Multiple Requests (`Utils::unwrap`)' + ); + + $transport = $this->prophesize(TransportInterface::class); + $transport->startUnaryCall(Argument::type(Call::class), Argument::type('array')) + ->shouldBeCalledTimes(3) + ->will(function (array $args) { + /** @var Call $call */ + $call = $args[0]; + $name = $call->getMessage()->getName(); + $secretId = explode('/', $name)[3]; + $response = (new AccessSecretVersionResponse()) + ->setName($name) + ->setPayload((new SecretPayload())->setData("val-$secretId")); + return Create::promiseFor($response); + }); + + $client = new SecretManagerServiceClient([ + 'credentials' => new InsecureCredentialsWrapper(), + 'transport' => $transport->reveal(), + ]); + + $snippet->replace( + <<<'PHP' +$client = new SecretManagerServiceClient([ + // Works with both 'grpc' (default) and 'rest' + 'transport' => 'grpc', +]); +PHP, + '' + ); + $snippet->addLocal('client', $client); + + $result = $snippet->invoke(); + $this->assertEquals( + <<<'EOF' +db-password: val-db-password +api-key: val-api-key +jwt-signing-key: val-jwt-signing-key + +EOF, + $result->output() + ); + } + + public function testHandlingPartialFailures() + { + $snippet = $this->snippetFromMarkdown( + self::ASYNC_FILE, + 'Handling Partial Failures (`Utils::settle`)' + ); + + $transport = $this->prophesize(TransportInterface::class); + $transport->startUnaryCall(Argument::type(Call::class), Argument::type('array')) + ->will(function (array $args) { + /** @var Call $call */ + $call = $args[0]; + $name = $call->getMessage()->getName(); + if (str_contains($name, '/missing/')) { + return Create::rejectionFor( + new ApiException('Secret not found', Code::NOT_FOUND, ApiStatus::NOT_FOUND) + ); + } + $response = (new AccessSecretVersionResponse()) + ->setName($name) + ->setPayload((new SecretPayload())->setData('secret-data')); + return Create::promiseFor($response); + }); + + $client = new SecretManagerServiceClient([ + 'credentials' => new InsecureCredentialsWrapper(), + 'disableRetries' => true, + 'transport' => $transport->reveal(), + ]); + + $snippet->replace('$client = new SecretManagerServiceClient();', ''); + $snippet->addLocal('client', $client); + + $result = $snippet->invoke(); + $this->assertEquals( + <<<'EOF' +existing succeeded: secret-data +missing failed: NOT_FOUND + +EOF, + $result->output() + ); + } + + public function testLimitingConcurrency() + { + $snippet = $this->snippetFromMarkdown( + self::ASYNC_FILE, + 'Limiting Concurrency (`EachPromise`)' + ); + + $inFlight = 0; + $maxObservedInFlight = 0; + + $transport = $this->prophesize(TransportInterface::class); + $transport->startUnaryCall(Argument::type(Call::class), Argument::type('array')) + ->shouldBeCalledTimes(5) + ->will(function () use (&$inFlight, &$maxObservedInFlight) { + $inFlight++; + $maxObservedInFlight = max($maxObservedInFlight, $inFlight); + $promise = new Promise(function () use (&$promise, &$inFlight) { + $inFlight--; + $promise->resolve((new PublishResponse())->setMessageIds(['msg-1'])); + }); + return $promise; + }); + + $publisher = new PublisherClient([ + 'credentials' => new InsecureCredentialsWrapper(), + 'transport' => $transport->reveal(), + ]); + + $snippet->replace('$publisher = new PublisherClient();', ''); + $snippet->addLocal('publisher', $publisher); + + $result = $snippet->invoke(); + $this->assertLessThanOrEqual(2, $maxObservedInFlight); + $this->assertEquals("Published 5 messages\n", $result->output()); + } + + public function testHandwrittenClientHelpers() + { + $snippet = $this->snippetFromMarkdown( + self::ASYNC_FILE, + 'Handwritten Client Helpers' + ); + + $obj1 = $this->prophesize(StorageObject::class); + $obj1->name()->willReturn('report-1.txt'); + $obj2 = $this->prophesize(StorageObject::class); + $obj2->name()->willReturn('report-2.txt'); + + $bucket = $this->prophesize(Bucket::class); + $bucket->uploadAsync('First report contents', ['name' => 'report-1.txt']) + ->shouldBeCalledOnce() + ->willReturn(Create::promiseFor($obj1->reveal())); + $bucket->uploadAsync('Second report contents', ['name' => 'report-2.txt']) + ->shouldBeCalledOnce() + ->willReturn(Create::promiseFor($obj2->reveal())); + + $storage = $this->prophesize(StorageClient::class); + $storage->bucket('my-bucket')->shouldBeCalledOnce()->willReturn($bucket->reveal()); + + $snippet->replace('$storage = new StorageClient();', ''); + $snippet->addLocal('storage', $storage->reveal()); + + $result = $snippet->invoke(); + $this->assertEquals( + <<<'EOF' +Uploaded report-1.txt +Uploaded report-2.txt + +EOF, + $result->output() + ); + } + + public function testDrivingFibersWithCurlMultiHandler() + { + $snippet = $this->snippetFromMarkdown( + self::ASYNC_FILE, + 'Driving Fibers with `CurlMultiHandler`' + ); + + $pendingResolvers = []; + $fakeCurlMulti = new class($pendingResolvers) { + private array $resolvers; + + public function __construct(array &$resolvers) + { + $this->resolvers = &$resolvers; + } + + public function tick(): void + { + while ($resolver = array_shift($this->resolvers)) { + $resolver(); + } + } + }; + + $mockHandler = function (RequestInterface $request) use (&$pendingResolvers) { + $promise = new Promise(); + $pendingResolvers[] = static function () use ($promise, $request) { + $parts = explode('/', trim($request->getUri()->getPath(), '/')); + $secretId = $parts[4] ?? 'unknown'; + $body = json_encode([ + 'name' => "projects/my-project/secrets/$secretId/versions/1", + 'payload' => ['data' => base64_encode("fiber-$secretId")], + ]); + $promise->resolve(new Response(200, ['Content-Type' => 'application/json'], $body)); + }; + return $promise; + }; + + $httpClient = new Client(['handler' => HandlerStack::create($mockHandler)]); + + $snippet->addUse(InsecureCredentialsWrapper::class); + $snippet->replace( + <<<'PHP' +$curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); +$httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); +PHP, + '' + ); + $snippet->replace( + "'transport' => 'rest',", + "'transport' => 'rest',\n 'credentials' => new InsecureCredentialsWrapper()," + ); + $snippet->addLocal('curlMulti', $fakeCurlMulti); + $snippet->addLocal('httpClient', $httpClient); + + $result = $snippet->invoke(); + $this->assertEquals( + <<<'EOF' +db-password: fiber-db-password +api-key: fiber-api-key +jwt-signing-key: fiber-jwt-signing-key + +EOF, + $result->output() + ); + } +} diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md new file mode 100644 index 000000000000..0f8765342ac8 --- /dev/null +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md @@ -0,0 +1,277 @@ +# Asynchronous Requests and Concurrency + +Every generated Google Cloud PHP V2 client (`*\Client\*Client`) provides an `*Async()` method alongside each synchronous RPC method—for example, `accessSecretVersionAsync()` alongside `accessSecretVersion()`. These methods return a [`GuzzleHttp\Promise\PromiseInterface`](https://github.com/guzzle/promises), allowing a single PHP process to execute multiple API calls concurrently over **both gRPC and REST**. + +* **gRPC (`'transport' => 'grpc'`, default when `ext-grpc` is installed):** Calling `*Async()` immediately dispatches the RPC onto the `grpc` C extension's background network threads over multiplexed HTTP/2 streams. +* **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. + +## 1. Concurrent Requests with Promises + +### Waiting on Multiple Requests (`Utils::unwrap`) + +Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` throws a `Google\ApiCore\ApiException` immediately. + +```php +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use GuzzleHttp\Promise\Utils; + +$client = new SecretManagerServiceClient([ + // Works with both 'grpc' (default) and 'rest' + 'transport' => 'grpc', +]); + +$secretIds = ['db-password', 'api-key', 'jwt-signing-key']; +$promises = []; + +foreach ($secretIds as $secretId) { + $versionName = SecretManagerServiceClient::secretVersionName( + 'my-project', + $secretId, + 'latest' + ); + $request = (new AccessSecretVersionRequest())->setName($versionName); + + // Starts the request without blocking + $promises[$secretId] = $client->accessSecretVersionAsync($request); +} + +// Wait for all in-flight requests to complete concurrently +$responses = Utils::unwrap($promises); + +foreach ($responses as $secretId => $response) { + printf("%s: %s\n", $secretId, $response->getPayload()->getData()); +} +``` + +### Handling Partial Failures (`Utils::settle`) + +When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or `PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. + +```php +use Google\ApiCore\ApiException; +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; + +$client = new SecretManagerServiceClient(); + +$promises = [ + 'existing' => $client->accessSecretVersionAsync( + (new AccessSecretVersionRequest())->setName( + SecretManagerServiceClient::secretVersionName('my-project', 'existing', 'latest') + ) + ), + 'missing' => $client->accessSecretVersionAsync( + (new AccessSecretVersionRequest())->setName( + SecretManagerServiceClient::secretVersionName('my-project', 'missing', 'latest') + ) + ), +]; + +$results = Utils::settle($promises)->wait(); + +foreach ($results as $key => $result) { + if ($result['state'] === PromiseInterface::FULFILLED) { + printf("%s succeeded: %s\n", $key, $result['value']->getPayload()->getData()); + } else { + /** @var ApiException $error */ + $error = $result['reason']; + printf("%s failed: %s\n", $key, $error->getStatus()); + } +} +``` + +### Limiting Concurrency (`EachPromise`) + +Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive concurrent streams or hits API rate limits. Yield promises lazily from a generator into `GuzzleHttp\Promise\EachPromise` with a fixed `concurrency` cap. + +```php +use Google\Cloud\PubSub\V1\Client\PublisherClient; +use Google\Cloud\PubSub\V1\PubsubMessage; +use Google\Cloud\PubSub\V1\PublishRequest; +use Google\Cloud\PubSub\V1\PublishResponse; +use GuzzleHttp\Promise\EachPromise; + +$publisher = new PublisherClient(); +$topicName = PublisherClient::topicName('my-project', 'my-topic'); +$payloads = ['event-1', 'event-2', 'event-3', 'event-4', 'event-5']; + +$promiseGenerator = (function () use ($publisher, $topicName, $payloads) { + foreach ($payloads as $payload) { + $request = (new PublishRequest()) + ->setTopic($topicName) + ->setMessages([ + (new PubsubMessage())->setData($payload), + ]); + + yield $payload => $publisher->publishAsync($request); + } +})(); + +$publishedCount = 0; +$eachPromise = new EachPromise($promiseGenerator, [ + // Keep at most 2 requests in flight at any time + 'concurrency' => 2, + 'fulfilled' => function (PublishResponse $response, string $payload) use (&$publishedCount) { + $publishedCount += count($response->getMessageIds()); + }, +]); + +$eachPromise->promise()->wait(); +printf("Published %d messages\n", $publishedCount); +``` + +## 2. Supported Call Types + +| Call Type | `*Async()` Return Type | Behavior | +| :--- | :--- | :--- | +| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | +| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `pageToken` explicitly to `*Async()`. | +| **Long-Running Operation (LRO)** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts](https://docs.cloud.google.com/php/docs/reference/help/core_concepts) for polling LROs. | +| **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | + +### Handwritten Client Helpers + +Most handwritten wrapper clients (`BigQueryClient`, `SpannerClient`, `FirestoreClient`) expose synchronous helper APIs; use the underlying generated `V1\Client\*Client` classes when you need `*Async()` methods. For Cloud Storage, `Google\Cloud\Storage\Bucket` and `StorageObject` provide `uploadAsync()` and `downloadAsStreamAsync()` directly: + +```php +use Google\Cloud\Storage\StorageClient; +use GuzzleHttp\Promise\Utils; + +$storage = new StorageClient(); +$bucket = $storage->bucket('my-bucket'); + +$files = [ + 'report-1.txt' => 'First report contents', + 'report-2.txt' => 'Second report contents', +]; + +$promises = []; +foreach ($files as $name => $contents) { + $promises[$name] = $bucket->uploadAsync($contents, ['name' => $name]); +} + +$objects = Utils::unwrap($promises); +foreach ($objects as $name => $object) { + printf("Uploaded %s\n", $object->name()); +} +``` + +## 3. Using PHP Fibers with the REST Transport + +PHP `Fiber`s allow you to write normal synchronous client code (such as `$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. + +Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's `CurlMultiHandler` (or an event loop like [`revolt/event-loop`](https://revolt.run/)) and pass a Fiber-aware `httpHandler` and `authHttpHandler` to the **`rest`** transport. + +> [!IMPORTANT] +> Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the `*Async()` methods shown in Section 1. + +### Driving Fibers with `CurlMultiHandler` + +The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. + +```php +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use GuzzleHttp\Client; +use GuzzleHttp\Handler\CurlMultiHandler; +use GuzzleHttp\HandlerStack; +use GuzzleHttp\Promise\Promise; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; +use Psr\Http\Message\RequestInterface; +use Psr\Http\Message\ResponseInterface; + +$curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); +$httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); + +// Suspends the current Fiber until Guzzle resolves the HTTP transfer +$asyncFiberHandler = function (RequestInterface $request, array $options = []) use ($httpClient): PromiseInterface { + $guzzlePromise = $httpClient->sendAsync($request, $options); + $fiber = Fiber::getCurrent(); + if ($fiber === null) { + return $guzzlePromise; + } + + return $promise = new Promise(function () use (&$promise, $guzzlePromise, $fiber) { + $guzzlePromise->then( + static fn () => $fiber->isSuspended() && $fiber->resume(), + static fn () => $fiber->isSuspended() && $fiber->resume() + ); + if ($guzzlePromise->getState() === PromiseInterface::PENDING) { + Fiber::suspend(); + } + try { + $promise->resolve($guzzlePromise->wait()); + } catch (\Throwable $e) { + $promise->reject($e); + } + }); +}; + +// Wraps the async handler for synchronous OAuth2 token fetches in google/auth +$syncFiberHandler = static fn (RequestInterface $request, array $options = []): ResponseInterface => + $asyncFiberHandler($request, $options)->wait(); + +$client = new SecretManagerServiceClient([ + 'transport' => 'rest', + 'credentialsConfig' => [ + 'authHttpHandler' => $syncFiberHandler, + ], + 'transportConfig' => [ + 'rest' => [ + 'httpHandler' => $asyncFiberHandler, + ], + ], +]); + +$secretIds = ['db-password', 'api-key', 'jwt-signing-key']; +$fibers = []; + +foreach ($secretIds as $secretId) { + $fiber = new Fiber(function () use ($client, $secretId): string { + $request = (new AccessSecretVersionRequest())->setName( + SecretManagerServiceClient::secretVersionName('my-project', $secretId, 'latest') + ); + + // Synchronous method call—suspends this Fiber while HTTP I/O is in flight + $response = $client->accessSecretVersion($request); + return $response->getPayload()->getData(); + }); + $fiber->start(); + $fibers[$secretId] = $fiber; +} + +// Tick Guzzle's curl_multi loop until all fibers complete +while (array_filter($fibers, static fn (Fiber $f) => !$f->isTerminated())) { + $curlMulti->tick(); + Utils::queue()->run(); +} + +foreach ($fibers as $secretId => $fiber) { + printf("%s: %s\n", $secretId, $fiber->getReturn()); +} +``` + +### Integrating with an Event Loop (`revolt/event-loop` / Amp) + +In long-running async applications built on [`revolt/event-loop`](https://revolt.run/) or [`amphp/amp`](https://amphp.org/), register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active instead of writing a manual `while` loop: + +```php +use Revolt\EventLoop; +use GuzzleHttp\Promise\Utils; + +// Register a periodic callback to advance cURL transfers on the Revolt loop +$timerId = EventLoop::repeat(0.01, static function () use ($curlMulti): void { + $curlMulti->tick(); + Utils::queue()->run(); +}); + +// Unreference the timer so it does not keep the process alive once work finishes +EventLoop::unreference($timerId); +``` + +> [!NOTE] +> Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread during backoff. In latency-sensitive event-loop servers, consider setting `'disableRetries' => true` on the client and handling retry delays with your event loop's non-blocking timer (such as `Amp\delay()`). diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md index 657cb94804b4..d7111921f9d2 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md @@ -104,6 +104,10 @@ See [Authentication](AUTHENTICATION.md) for details and examples. Please see our [Debugging guide](DEBUG.md) for more information about the debugging tools. +## Asynchronous Requests + +Every generated V2 client exposes `*Async()` methods returning Guzzle Promises for concurrent requests over both gRPC and REST. See [Asynchronous Requests and Concurrency](ASYNC.md) for examples using Promises and PHP Fibers. + ## gRPC and Protobuf Many clients in Google Cloud PHP offer support for gRPC, either as an option or a requirement. gRPC diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/toc.yml b/dev/tests/fixtures/docfx/ProductNeutralGuides/toc.yml index 3cf75f4cfba2..271af19c7ff1 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/toc.yml +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/toc.yml @@ -14,6 +14,9 @@ - name: 'Client Configuration' href: client_configuration.md + - + name: 'Asynchronous Requests' + href: async.md - name: 'OCC for IAM' href: occ_for_iam.md From e9aa9d49b46520e529db7664464a1e724cec8f95 Mon Sep 17 00:00:00 2001 From: Brent Shaffer Date: Thu, 12 Nov 2026 18:45:08 +0000 Subject: [PATCH 2/5] docs: wrap lines at 100 characters --- ASYNC.md | 89 ++++++++++++++----- README.md | 4 +- .../docfx/ProductNeutralGuides/async.md | 89 ++++++++++++++----- .../ProductNeutralGuides/getting-started.md | 4 +- 4 files changed, 140 insertions(+), 46 deletions(-) diff --git a/ASYNC.md b/ASYNC.md index 0f8765342ac8..d29a8c048b15 100644 --- a/ASYNC.md +++ b/ASYNC.md @@ -1,15 +1,26 @@ # Asynchronous Requests and Concurrency -Every generated Google Cloud PHP V2 client (`*\Client\*Client`) provides an `*Async()` method alongside each synchronous RPC method—for example, `accessSecretVersionAsync()` alongside `accessSecretVersion()`. These methods return a [`GuzzleHttp\Promise\PromiseInterface`](https://github.com/guzzle/promises), allowing a single PHP process to execute multiple API calls concurrently over **both gRPC and REST**. +Every generated Google Cloud PHP V2 client (`*\Client\*Client`) provides an `*Async()` method +alongside each synchronous RPC method—for example, `accessSecretVersionAsync()` alongside +`accessSecretVersion()`. These methods return a +[`GuzzleHttp\Promise\PromiseInterface`][guzzle-promises], allowing a single PHP process to execute +multiple API calls concurrently over **both gRPC and REST**. -* **gRPC (`'transport' => 'grpc'`, default when `ext-grpc` is installed):** Calling `*Async()` immediately dispatches the RPC onto the `grpc` C extension's background network threads over multiplexed HTTP/2 streams. -* **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. +* **gRPC (`'transport' => 'grpc'`, default when `ext-grpc` is installed):** Calling `*Async()` + immediately dispatches the RPC onto the `grpc` C extension's background network threads over + multiplexed HTTP/2 streams. +* **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's + `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. + +[guzzle-promises]: https://github.com/guzzle/promises ## 1. Concurrent Requests with Promises ### Waiting on Multiple Requests (`Utils::unwrap`) -Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` throws a `Google\ApiCore\ApiException` immediately. +Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently +and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` +throws a `Google\ApiCore\ApiException` immediately. ```php use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; @@ -46,7 +57,9 @@ foreach ($responses as $secretId => $response) { ### Handling Partial Failures (`Utils::settle`) -When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or `PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. +When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. +Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or +`PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. ```php use Google\ApiCore\ApiException; @@ -85,7 +98,9 @@ foreach ($results as $key => $result) { ### Limiting Concurrency (`EachPromise`) -Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive concurrent streams or hits API rate limits. Yield promises lazily from a generator into `GuzzleHttp\Promise\EachPromise` with a fixed `concurrency` cap. +Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive +concurrent streams or hits API rate limits. Yield promises lazily from a generator into +`GuzzleHttp\Promise\EachPromise` with a fixed `concurrency` cap. ```php use Google\Cloud\PubSub\V1\Client\PublisherClient; @@ -125,16 +140,23 @@ printf("Published %d messages\n", $publishedCount); ## 2. Supported Call Types -| Call Type | `*Async()` Return Type | Behavior | -| :--- | :--- | :--- | -| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | -| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `pageToken` explicitly to `*Async()`. | -| **Long-Running Operation (LRO)** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts](https://docs.cloud.google.com/php/docs/reference/help/core_concepts) for polling LROs. | -| **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | +* **Unary (`PromiseInterface`):** Resolves to the protobuf response message. +* **Paginated (`PromiseInterface`):** Resolves the first page asynchronously. + Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate + asynchronously, pass `pageToken` explicitly to `*Async()`. +* **Long-Running Operation (`PromiseInterface`):** Resolves once the server + *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. +* **Streaming & Resumable Uploads:** Not supported via `*Async()` (throws `ValidationException`). + Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. + +[core-concepts]: https://docs.cloud.google.com/php/docs/reference/help/core_concepts ### Handwritten Client Helpers -Most handwritten wrapper clients (`BigQueryClient`, `SpannerClient`, `FirestoreClient`) expose synchronous helper APIs; use the underlying generated `V1\Client\*Client` classes when you need `*Async()` methods. For Cloud Storage, `Google\Cloud\Storage\Bucket` and `StorageObject` provide `uploadAsync()` and `downloadAsStreamAsync()` directly: +Most handwritten wrapper clients (`BigQueryClient`, `SpannerClient`, `FirestoreClient`) expose +synchronous helper APIs; use the underlying generated `V1\Client\*Client` classes when you need +`*Async()` methods. For Cloud Storage, `Google\Cloud\Storage\Bucket` and `StorageObject` provide +`uploadAsync()` and `downloadAsStreamAsync()` directly: ```php use Google\Cloud\Storage\StorageClient; @@ -161,16 +183,27 @@ foreach ($objects as $name => $object) { ## 3. Using PHP Fibers with the REST Transport -PHP `Fiber`s allow you to write normal synchronous client code (such as `$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. +PHP `Fiber`s allow you to write normal synchronous client code (such as +`$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network +I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. -Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's `CurlMultiHandler` (or an event loop like [`revolt/event-loop`](https://revolt.run/)) and pass a Fiber-aware `httpHandler` and `authHttpHandler` to the **`rest`** transport. +Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's +`CurlMultiHandler` (or an event loop like [`revolt/event-loop`][revolt]) and pass a Fiber-aware +`httpHandler` and `authHttpHandler` to the **`rest`** transport. > [!IMPORTANT] -> Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the `*Async()` methods shown in Section 1. +> Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, +> synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which +> does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the +> `*Async()` methods shown in Section 1. + +[revolt]: https://revolt.run/ ### Driving Fibers with `CurlMultiHandler` -The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. +The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional +dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests +and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. ```php use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; @@ -188,7 +221,10 @@ $curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); $httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); // Suspends the current Fiber until Guzzle resolves the HTTP transfer -$asyncFiberHandler = function (RequestInterface $request, array $options = []) use ($httpClient): PromiseInterface { +$asyncFiberHandler = function ( + RequestInterface $request, + array $options = [] +) use ($httpClient): PromiseInterface { $guzzlePromise = $httpClient->sendAsync($request, $options); $fiber = Fiber::getCurrent(); if ($fiber === null) { @@ -212,8 +248,10 @@ $asyncFiberHandler = function (RequestInterface $request, array $options = []) u }; // Wraps the async handler for synchronous OAuth2 token fetches in google/auth -$syncFiberHandler = static fn (RequestInterface $request, array $options = []): ResponseInterface => - $asyncFiberHandler($request, $options)->wait(); +$syncFiberHandler = static fn ( + RequestInterface $request, + array $options = [] +): ResponseInterface => $asyncFiberHandler($request, $options)->wait(); $client = new SecretManagerServiceClient([ 'transport' => 'rest', @@ -257,7 +295,9 @@ foreach ($fibers as $secretId => $fiber) { ### Integrating with an Event Loop (`revolt/event-loop` / Amp) -In long-running async applications built on [`revolt/event-loop`](https://revolt.run/) or [`amphp/amp`](https://amphp.org/), register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active instead of writing a manual `while` loop: +In long-running async applications built on [`revolt/event-loop`][revolt] or [`amphp/amp`][amp], +register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active +instead of writing a manual `while` loop: ```php use Revolt\EventLoop; @@ -273,5 +313,10 @@ $timerId = EventLoop::repeat(0.01, static function () use ($curlMulti): void { EventLoop::unreference($timerId); ``` +[amp]: https://amphp.org/ + > [!NOTE] -> Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread during backoff. In latency-sensitive event-loop servers, consider setting `'disableRetries' => true` on the client and handling retry delays with your event loop's non-blocking timer (such as `Amp\delay()`). +> Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread +> during backoff. In latency-sensitive event-loop servers, consider setting +> `'disableRetries' => true` on the client and handling retry delays with your event loop's +> non-blocking timer (such as `Amp\delay()`). diff --git a/README.md b/README.md index d7111921f9d2..41f9f42734f1 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,9 @@ Please see our [Debugging guide](DEBUG.md) for more information about the debugg ## Asynchronous Requests -Every generated V2 client exposes `*Async()` methods returning Guzzle Promises for concurrent requests over both gRPC and REST. See [Asynchronous Requests and Concurrency](ASYNC.md) for examples using Promises and PHP Fibers. +Every generated V2 client exposes `*Async()` methods returning Guzzle Promises for concurrent +requests over both gRPC and REST. See [Asynchronous Requests and Concurrency](ASYNC.md) for +examples using Promises and PHP Fibers. ## gRPC and Protobuf diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md index 0f8765342ac8..d29a8c048b15 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md @@ -1,15 +1,26 @@ # Asynchronous Requests and Concurrency -Every generated Google Cloud PHP V2 client (`*\Client\*Client`) provides an `*Async()` method alongside each synchronous RPC method—for example, `accessSecretVersionAsync()` alongside `accessSecretVersion()`. These methods return a [`GuzzleHttp\Promise\PromiseInterface`](https://github.com/guzzle/promises), allowing a single PHP process to execute multiple API calls concurrently over **both gRPC and REST**. +Every generated Google Cloud PHP V2 client (`*\Client\*Client`) provides an `*Async()` method +alongside each synchronous RPC method—for example, `accessSecretVersionAsync()` alongside +`accessSecretVersion()`. These methods return a +[`GuzzleHttp\Promise\PromiseInterface`][guzzle-promises], allowing a single PHP process to execute +multiple API calls concurrently over **both gRPC and REST**. -* **gRPC (`'transport' => 'grpc'`, default when `ext-grpc` is installed):** Calling `*Async()` immediately dispatches the RPC onto the `grpc` C extension's background network threads over multiplexed HTTP/2 streams. -* **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. +* **gRPC (`'transport' => 'grpc'`, default when `ext-grpc` is installed):** Calling `*Async()` + immediately dispatches the RPC onto the `grpc` C extension's background network threads over + multiplexed HTTP/2 streams. +* **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's + `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. + +[guzzle-promises]: https://github.com/guzzle/promises ## 1. Concurrent Requests with Promises ### Waiting on Multiple Requests (`Utils::unwrap`) -Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` throws a `Google\ApiCore\ApiException` immediately. +Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently +and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` +throws a `Google\ApiCore\ApiException` immediately. ```php use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; @@ -46,7 +57,9 @@ foreach ($responses as $secretId => $response) { ### Handling Partial Failures (`Utils::settle`) -When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or `PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. +When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. +Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or +`PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. ```php use Google\ApiCore\ApiException; @@ -85,7 +98,9 @@ foreach ($results as $key => $result) { ### Limiting Concurrency (`EachPromise`) -Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive concurrent streams or hits API rate limits. Yield promises lazily from a generator into `GuzzleHttp\Promise\EachPromise` with a fixed `concurrency` cap. +Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive +concurrent streams or hits API rate limits. Yield promises lazily from a generator into +`GuzzleHttp\Promise\EachPromise` with a fixed `concurrency` cap. ```php use Google\Cloud\PubSub\V1\Client\PublisherClient; @@ -125,16 +140,23 @@ printf("Published %d messages\n", $publishedCount); ## 2. Supported Call Types -| Call Type | `*Async()` Return Type | Behavior | -| :--- | :--- | :--- | -| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | -| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `pageToken` explicitly to `*Async()`. | -| **Long-Running Operation (LRO)** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts](https://docs.cloud.google.com/php/docs/reference/help/core_concepts) for polling LROs. | -| **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | +* **Unary (`PromiseInterface`):** Resolves to the protobuf response message. +* **Paginated (`PromiseInterface`):** Resolves the first page asynchronously. + Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate + asynchronously, pass `pageToken` explicitly to `*Async()`. +* **Long-Running Operation (`PromiseInterface`):** Resolves once the server + *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. +* **Streaming & Resumable Uploads:** Not supported via `*Async()` (throws `ValidationException`). + Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. + +[core-concepts]: https://docs.cloud.google.com/php/docs/reference/help/core_concepts ### Handwritten Client Helpers -Most handwritten wrapper clients (`BigQueryClient`, `SpannerClient`, `FirestoreClient`) expose synchronous helper APIs; use the underlying generated `V1\Client\*Client` classes when you need `*Async()` methods. For Cloud Storage, `Google\Cloud\Storage\Bucket` and `StorageObject` provide `uploadAsync()` and `downloadAsStreamAsync()` directly: +Most handwritten wrapper clients (`BigQueryClient`, `SpannerClient`, `FirestoreClient`) expose +synchronous helper APIs; use the underlying generated `V1\Client\*Client` classes when you need +`*Async()` methods. For Cloud Storage, `Google\Cloud\Storage\Bucket` and `StorageObject` provide +`uploadAsync()` and `downloadAsStreamAsync()` directly: ```php use Google\Cloud\Storage\StorageClient; @@ -161,16 +183,27 @@ foreach ($objects as $name => $object) { ## 3. Using PHP Fibers with the REST Transport -PHP `Fiber`s allow you to write normal synchronous client code (such as `$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. +PHP `Fiber`s allow you to write normal synchronous client code (such as +`$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network +I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. -Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's `CurlMultiHandler` (or an event loop like [`revolt/event-loop`](https://revolt.run/)) and pass a Fiber-aware `httpHandler` and `authHttpHandler` to the **`rest`** transport. +Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's +`CurlMultiHandler` (or an event loop like [`revolt/event-loop`][revolt]) and pass a Fiber-aware +`httpHandler` and `authHttpHandler` to the **`rest`** transport. > [!IMPORTANT] -> Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the `*Async()` methods shown in Section 1. +> Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, +> synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which +> does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the +> `*Async()` methods shown in Section 1. + +[revolt]: https://revolt.run/ ### Driving Fibers with `CurlMultiHandler` -The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. +The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional +dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests +and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. ```php use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; @@ -188,7 +221,10 @@ $curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); $httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); // Suspends the current Fiber until Guzzle resolves the HTTP transfer -$asyncFiberHandler = function (RequestInterface $request, array $options = []) use ($httpClient): PromiseInterface { +$asyncFiberHandler = function ( + RequestInterface $request, + array $options = [] +) use ($httpClient): PromiseInterface { $guzzlePromise = $httpClient->sendAsync($request, $options); $fiber = Fiber::getCurrent(); if ($fiber === null) { @@ -212,8 +248,10 @@ $asyncFiberHandler = function (RequestInterface $request, array $options = []) u }; // Wraps the async handler for synchronous OAuth2 token fetches in google/auth -$syncFiberHandler = static fn (RequestInterface $request, array $options = []): ResponseInterface => - $asyncFiberHandler($request, $options)->wait(); +$syncFiberHandler = static fn ( + RequestInterface $request, + array $options = [] +): ResponseInterface => $asyncFiberHandler($request, $options)->wait(); $client = new SecretManagerServiceClient([ 'transport' => 'rest', @@ -257,7 +295,9 @@ foreach ($fibers as $secretId => $fiber) { ### Integrating with an Event Loop (`revolt/event-loop` / Amp) -In long-running async applications built on [`revolt/event-loop`](https://revolt.run/) or [`amphp/amp`](https://amphp.org/), register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active instead of writing a manual `while` loop: +In long-running async applications built on [`revolt/event-loop`][revolt] or [`amphp/amp`][amp], +register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active +instead of writing a manual `while` loop: ```php use Revolt\EventLoop; @@ -273,5 +313,10 @@ $timerId = EventLoop::repeat(0.01, static function () use ($curlMulti): void { EventLoop::unreference($timerId); ``` +[amp]: https://amphp.org/ + > [!NOTE] -> Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread during backoff. In latency-sensitive event-loop servers, consider setting `'disableRetries' => true` on the client and handling retry delays with your event loop's non-blocking timer (such as `Amp\delay()`). +> Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread +> during backoff. In latency-sensitive event-loop servers, consider setting +> `'disableRetries' => true` on the client and handling retry delays with your event loop's +> non-blocking timer (such as `Amp\delay()`). diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md index d7111921f9d2..41f9f42734f1 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/getting-started.md @@ -106,7 +106,9 @@ Please see our [Debugging guide](DEBUG.md) for more information about the debugg ## Asynchronous Requests -Every generated V2 client exposes `*Async()` methods returning Guzzle Promises for concurrent requests over both gRPC and REST. See [Asynchronous Requests and Concurrency](ASYNC.md) for examples using Promises and PHP Fibers. +Every generated V2 client exposes `*Async()` methods returning Guzzle Promises for concurrent +requests over both gRPC and REST. See [Asynchronous Requests and Concurrency](ASYNC.md) for +examples using Promises and PHP Fibers. ## gRPC and Protobuf From 35bdfb2a8064a98533070cc74b77381ee1750729 Mon Sep 17 00:00:00 2001 From: Brent Shaffer Date: Thu, 12 Nov 2026 18:56:59 +0000 Subject: [PATCH 3/5] docs: add concurrent pagination example and simplify Fiber section --- ASYNC.md | 210 +++++++++-------- .../ProductNeutralGuides/AsyncTest.php | 219 +++++++++++++++--- .../docfx/ProductNeutralGuides/async.md | 210 +++++++++-------- 3 files changed, 412 insertions(+), 227 deletions(-) diff --git a/ASYNC.md b/ASYNC.md index d29a8c048b15..4d04e163022d 100644 --- a/ASYNC.md +++ b/ASYNC.md @@ -138,12 +138,76 @@ $eachPromise->promise()->wait(); printf("Published %d messages\n", $publishedCount); ``` +### Paginating Concurrently + +For a single list query, async pagination is no faster than synchronous `foreach` iteration because +each page requires the `nextPageToken` returned by the previous page. Async pagination is useful +when listing across **multiple parents** (such as projects or regions) concurrently, or when +overlapping page fetches with per-item async RPCs. + +Inside a `.then()` callback, iterate `$response->getPage()` (the current page only) rather than +`$response` directly—iterating `$response` calls `Page::getNextPage()`, which blocks synchronously +via `wait()`—and chain the next `*Async()` call using `$page->getNextPageToken()`: + +```php +use Google\ApiCore\PagedListResponse; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use Google\Cloud\SecretManager\V1\ListSecretsRequest; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; + +function listAllSecretsAsync( + SecretManagerServiceClient $client, + string $parent, + string $pageToken = '', + array $secrets = [] +): PromiseInterface { + $request = (new ListSecretsRequest()) + ->setParent($parent) + ->setPageToken($pageToken); + + return $client->listSecretsAsync($request)->then( + function (PagedListResponse $response) use ($client, $parent, $secrets) { + // Iterate getPage() (current page only), NOT $response directly + $page = $response->getPage(); + foreach ($page as $secret) { + $secrets[] = $secret; + } + + if ($page->hasNextPage()) { + return listAllSecretsAsync( + $client, + $parent, + $page->getNextPageToken(), + $secrets + ); + } + + return $secrets; + } + ); +} + +$client = new SecretManagerServiceClient(); +$parents = ['projects/proj-a', 'projects/proj-b']; + +$promises = []; +foreach ($parents as $parent) { + $promises[$parent] = listAllSecretsAsync($client, $parent); +} + +$secretsByProject = Utils::unwrap($promises); +foreach ($secretsByProject as $parent => $secrets) { + printf("%s: %d secrets\n", $parent, count($secrets)); +} +``` + ## 2. Supported Call Types * **Unary (`PromiseInterface`):** Resolves to the protobuf response message. * **Paginated (`PromiseInterface`):** Resolves the first page asynchronously. - Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate - asynchronously, pass `pageToken` explicitly to `*Async()`. + See [Paginating Concurrently](#paginating-concurrently) for fetching subsequent pages without + blocking. * **Long-Running Operation (`PromiseInterface`):** Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. * **Streaming & Resumable Uploads:** Not supported via `*Async()` (throws `ValidationException`). @@ -183,138 +247,90 @@ foreach ($objects as $name => $object) { ## 3. Using PHP Fibers with the REST Transport -PHP `Fiber`s allow you to write normal synchronous client code (such as -`$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network -I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. +In Fiber-based applications (such as [AMPHP][amp]), you can run standard synchronous client methods +concurrently over the **`rest`** transport without chaining `.then()` callbacks by routing Guzzle +requests through [`amphp/http-client-guzzle-adapter`][amp-guzzle-adapter]: -Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's -`CurlMultiHandler` (or an event loop like [`revolt/event-loop`][revolt]) and pass a Fiber-aware -`httpHandler` and `authHttpHandler` to the **`rest`** transport. +```sh +composer require amphp/amp amphp/http-client-guzzle-adapter +``` > [!IMPORTANT] > Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, > synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which -> does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the +> does not expose pollable sockets to PHP's event loop. For concurrent gRPC calls, use the > `*Async()` methods shown in Section 1. -[revolt]: https://revolt.run/ +[amp]: https://amphp.org/ +[amp-guzzle-adapter]: https://github.com/amphp/http-client-guzzle-adapter -### Driving Fibers with `CurlMultiHandler` +### 1. Configure the REST Client -The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional -dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests -and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. +Build an HTTP handler around `GuzzleHandlerAdapter` with `HttpHandlerFactory::build()` and pass it +to both `credentialsConfig` (so OAuth2 token refreshes are non-blocking) and `transportConfig`: ```php -use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter; +use Google\Auth\HttpHandler\HttpHandlerFactory; use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; use GuzzleHttp\Client; -use GuzzleHttp\Handler\CurlMultiHandler; use GuzzleHttp\HandlerStack; -use GuzzleHttp\Promise\Promise; -use GuzzleHttp\Promise\PromiseInterface; -use GuzzleHttp\Promise\Utils; -use Psr\Http\Message\RequestInterface; -use Psr\Http\Message\ResponseInterface; - -$curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); -$httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); - -// Suspends the current Fiber until Guzzle resolves the HTTP transfer -$asyncFiberHandler = function ( - RequestInterface $request, - array $options = [] -) use ($httpClient): PromiseInterface { - $guzzlePromise = $httpClient->sendAsync($request, $options); - $fiber = Fiber::getCurrent(); - if ($fiber === null) { - return $guzzlePromise; - } - return $promise = new Promise(function () use (&$promise, $guzzlePromise, $fiber) { - $guzzlePromise->then( - static fn () => $fiber->isSuspended() && $fiber->resume(), - static fn () => $fiber->isSuspended() && $fiber->resume() - ); - if ($guzzlePromise->getState() === PromiseInterface::PENDING) { - Fiber::suspend(); - } - try { - $promise->resolve($guzzlePromise->wait()); - } catch (\Throwable $e) { - $promise->reject($e); - } - }); -}; - -// Wraps the async handler for synchronous OAuth2 token fetches in google/auth -$syncFiberHandler = static fn ( - RequestInterface $request, - array $options = [] -): ResponseInterface => $asyncFiberHandler($request, $options)->wait(); +// Route Guzzle requests through AMPHP's Fiber-native HTTP client +$httpClient = new Client([ + 'handler' => HandlerStack::create(new GuzzleHandlerAdapter()), +]); +$httpHandler = HttpHandlerFactory::build($httpClient); +// Configure both auth token refreshes and REST calls to use the handler $client = new SecretManagerServiceClient([ 'transport' => 'rest', 'credentialsConfig' => [ - 'authHttpHandler' => $syncFiberHandler, + 'authHttpHandler' => $httpHandler, ], 'transportConfig' => [ 'rest' => [ - 'httpHandler' => $asyncFiberHandler, + 'httpHandler' => [$httpHandler, 'async'], ], ], ]); +``` + +### 2. Run Synchronous Calls Concurrently + +With the Fiber-backed handler configured, standard synchronous methods (including `foreach` +pagination across pages) automatically suspend the current Fiber while waiting on HTTP I/O: + +```php +use Amp\Future; +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use function Amp\async; $secretIds = ['db-password', 'api-key', 'jwt-signing-key']; -$fibers = []; +$futures = []; foreach ($secretIds as $secretId) { - $fiber = new Fiber(function () use ($client, $secretId): string { - $request = (new AccessSecretVersionRequest())->setName( - SecretManagerServiceClient::secretVersionName('my-project', $secretId, 'latest') + $futures[$secretId] = async(function () use ($client, $secretId): string { + $versionName = SecretManagerServiceClient::secretVersionName( + 'my-project', + $secretId, + 'latest' ); + $request = (new AccessSecretVersionRequest())->setName($versionName); - // Synchronous method call—suspends this Fiber while HTTP I/O is in flight - $response = $client->accessSecretVersion($request); - return $response->getPayload()->getData(); + // Suspends the current Fiber automatically while waiting on HTTP I/O + return $client->accessSecretVersion($request)->getPayload()->getData(); }); - $fiber->start(); - $fibers[$secretId] = $fiber; } -// Tick Guzzle's curl_multi loop until all fibers complete -while (array_filter($fibers, static fn (Fiber $f) => !$f->isTerminated())) { - $curlMulti->tick(); - Utils::queue()->run(); +// Wait for all Fibers to finish and collect their return values +$secrets = Future\await($futures); +foreach ($secrets as $secretId => $value) { + printf("%s: %s\n", $secretId, $value); } - -foreach ($fibers as $secretId => $fiber) { - printf("%s: %s\n", $secretId, $fiber->getReturn()); -} -``` - -### Integrating with an Event Loop (`revolt/event-loop` / Amp) - -In long-running async applications built on [`revolt/event-loop`][revolt] or [`amphp/amp`][amp], -register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active -instead of writing a manual `while` loop: - -```php -use Revolt\EventLoop; -use GuzzleHttp\Promise\Utils; - -// Register a periodic callback to advance cURL transfers on the Revolt loop -$timerId = EventLoop::repeat(0.01, static function () use ($curlMulti): void { - $curlMulti->tick(); - Utils::queue()->run(); -}); - -// Unreference the timer so it does not keep the process alive once work finishes -EventLoop::unreference($timerId); ``` -[amp]: https://amphp.org/ - > [!NOTE] > Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread > during backoff. In latency-sensitive event-loop servers, consider setting diff --git a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php index 2b0f0ddfafaf..6735c466dc6a 100644 --- a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php +++ b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php @@ -17,29 +17,41 @@ namespace Google\Cloud\Dev\Tests\Snippet; +use Fiber; use Google\ApiCore\ApiException; use Google\ApiCore\ApiStatus; use Google\ApiCore\Call; use Google\ApiCore\InsecureCredentialsWrapper; use Google\ApiCore\Transport\TransportInterface; +use Google\Auth\Credentials\ServiceAccountCredentials; +use Google\Auth\HttpHandler\Guzzle7HttpHandler; +use Google\Auth\HttpHandler\HttpHandlerFactory; use Google\Cloud\Core\Testing\Snippet\SnippetTestCase; use Google\Cloud\PubSub\V1\Client\PublisherClient; use Google\Cloud\PubSub\V1\PublishResponse; use Google\Cloud\SecretManager\V1\AccessSecretVersionResponse; use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use Google\Cloud\SecretManager\V1\ListSecretsRequest; +use Google\Cloud\SecretManager\V1\ListSecretsResponse; +use Google\Cloud\SecretManager\V1\Secret; use Google\Cloud\SecretManager\V1\SecretPayload; use Google\Cloud\Storage\Bucket; use Google\Cloud\Storage\StorageClient; use Google\Cloud\Storage\StorageObject; use Google\Rpc\Code; use GuzzleHttp\Client; +use GuzzleHttp\Handler\MockHandler; use GuzzleHttp\HandlerStack; use GuzzleHttp\Promise\Create; use GuzzleHttp\Promise\Promise; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; use GuzzleHttp\Psr7\Response; use Prophecy\Argument; use Prophecy\PhpUnit\ProphecyTrait; use Psr\Http\Message\RequestInterface; +use ReflectionClass; +use ReflectionFunction; /** * @group docs @@ -179,6 +191,75 @@ public function testLimitingConcurrency() $this->assertEquals("Published 5 messages\n", $result->output()); } + public function testPaginatingConcurrently() + { + $snippet = $this->snippetFromMarkdown( + self::ASYNC_FILE, + 'Paginating Concurrently' + ); + + $transport = $this->prophesize(TransportInterface::class); + $transport->startUnaryCall(Argument::type(Call::class), Argument::type('array')) + ->shouldBeCalledTimes(3) + ->will(function (array $args) { + /** @var Call $call */ + $call = $args[0]; + /** @var ListSecretsRequest $request */ + $request = $call->getMessage(); + $parent = $request->getParent(); + $token = $request->getPageToken(); + + if ($parent === 'projects/proj-a' && $token === '') { + return Create::promiseFor( + (new ListSecretsResponse()) + ->setSecrets([ + (new Secret())->setName('projects/proj-a/secrets/s1'), + (new Secret())->setName('projects/proj-a/secrets/s2'), + ]) + ->setNextPageToken('page-2') + ); + } + + if ($parent === 'projects/proj-a' && $token === 'page-2') { + return Create::promiseFor( + (new ListSecretsResponse()) + ->setSecrets([ + (new Secret())->setName('projects/proj-a/secrets/s3'), + ]) + ); + } + + return Create::promiseFor( + (new ListSecretsResponse()) + ->setSecrets([ + (new Secret())->setName('projects/proj-b/secrets/s1'), + ]) + ); + }); + + $client = new SecretManagerServiceClient([ + 'credentials' => new InsecureCredentialsWrapper(), + 'transport' => $transport->reveal(), + ]); + + $snippet->replace( + '$client = new SecretManagerServiceClient();', + 'global $testClient; $client = $testClient;' + ); + global $testClient; + $testClient = $client; + + $result = $snippet->invoke(); + $this->assertEquals( + <<<'EOF' +projects/proj-a: 3 secrets +projects/proj-b: 1 secrets + +EOF, + $result->output() + ); + } + public function testHandwrittenClientHelpers() { $snippet = $this->snippetFromMarkdown( @@ -216,60 +297,132 @@ public function testHandwrittenClientHelpers() ); } - public function testDrivingFibersWithCurlMultiHandler() + public function testConfigureRestClientWithFibers() { $snippet = $this->snippetFromMarkdown( self::ASYNC_FILE, - 'Driving Fibers with `CurlMultiHandler`' + '1. Configure the REST Client' ); - $pendingResolvers = []; - $fakeCurlMulti = new class($pendingResolvers) { - private array $resolvers; + $creds = $this->prophesize(ServiceAccountCredentials::class); + $snippet->addUse(MockHandler::class); + $snippet->replace( + 'use Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter;', + '' + ); + $snippet->replace('new GuzzleHandlerAdapter()', 'new MockHandler()'); + $snippet->replace( + "'transport' => 'rest',", + "'transport' => 'rest',\n 'credentials' => \$creds," + ); + $snippet->addLocal('creds', $creds->reveal()); + + $res = $snippet->invoke(['client', 'httpHandler']); + [$client, $httpHandler] = $res->returnVal(); + + $this->assertInstanceOf(SecretManagerServiceClient::class, $client); + $this->assertInstanceOf(Guzzle7HttpHandler::class, $httpHandler); + + $cw = (new ReflectionClass($client)) + ->getProperty('credentialsWrapper') + ->getValue($client); + $authHttp = (new ReflectionClass($cw)) + ->getProperty('authHttpHandler') + ->getValue($cw); + $this->assertSame($httpHandler, $authHttp); + + $transport = (new ReflectionClass($client)) + ->getProperty('transport') + ->getValue($client); + $restHttpClosure = (new ReflectionClass($transport)) + ->getProperty('httpHandler') + ->getValue($transport); + $this->assertSame( + $httpHandler, + (new ReflectionFunction($restHttpClosure))->getClosureThis() + ); + } - public function __construct(array &$resolvers) - { - $this->resolvers = &$resolvers; - } + public function testRunSynchronousCallsConcurrentlyInFibers() + { + if (!function_exists('Amp\async')) { + eval(<<<'PHP' +namespace Amp { + function async(callable $fn): \Fiber { + $fiber = new \Fiber($fn); + $fiber->start(); + return $fiber; + } +} +namespace Amp\Future { + function await(array $futures): array { + global $drainFiberResolvers; + ($drainFiberResolvers)(); + return array_map(static fn (\Fiber $f) => $f->getReturn(), $futures); + } +} +PHP); + } - public function tick(): void - { - while ($resolver = array_shift($this->resolvers)) { - $resolver(); - } + $pendingResolvers = []; + global $drainFiberResolvers; + $drainFiberResolvers = static function () use (&$pendingResolvers): void { + // All 3 Fibers must have started and suspended before any response resolves + while ($resolver = array_shift($pendingResolvers)) { + $resolver(); + Utils::queue()->run(); } }; - $mockHandler = function (RequestInterface $request) use (&$pendingResolvers) { - $promise = new Promise(); - $pendingResolvers[] = static function () use ($promise, $request) { + $mockAdapter = static function ( + RequestInterface $request + ) use (&$pendingResolvers): PromiseInterface { + $guzzlePromise = new Promise(); + $fiber = Fiber::getCurrent(); + $pendingResolvers[] = static function () use ($guzzlePromise, $request): void { $parts = explode('/', trim($request->getUri()->getPath(), '/')); $secretId = $parts[4] ?? 'unknown'; $body = json_encode([ 'name' => "projects/my-project/secrets/$secretId/versions/1", 'payload' => ['data' => base64_encode("fiber-$secretId")], ]); - $promise->resolve(new Response(200, ['Content-Type' => 'application/json'], $body)); + $guzzlePromise->resolve( + new Response(200, ['Content-Type' => 'application/json'], $body) + ); }; - return $promise; + + return $promise = new Promise( + static function () use (&$promise, $guzzlePromise, $fiber): void { + $guzzlePromise->then( + static fn () => $fiber && $fiber->isSuspended() && $fiber->resume(), + static fn () => $fiber && $fiber->isSuspended() && $fiber->resume() + ); + if ($fiber && $guzzlePromise->getState() === PromiseInterface::PENDING) { + Fiber::suspend(); + } + $promise->resolve($guzzlePromise->wait()); + } + ); }; - $httpClient = new Client(['handler' => HandlerStack::create($mockHandler)]); + $httpClient = new Client(['handler' => HandlerStack::create($mockAdapter)]); + $httpHandler = HttpHandlerFactory::build($httpClient); - $snippet->addUse(InsecureCredentialsWrapper::class); - $snippet->replace( - <<<'PHP' -$curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); -$httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); -PHP, - '' - ); - $snippet->replace( - "'transport' => 'rest',", - "'transport' => 'rest',\n 'credentials' => new InsecureCredentialsWrapper()," + $client = new SecretManagerServiceClient([ + 'transport' => 'rest', + 'credentials' => new InsecureCredentialsWrapper(), + 'transportConfig' => [ + 'rest' => [ + 'httpHandler' => [$httpHandler, 'async'], + ], + ], + ]); + + $snippet = $this->snippetFromMarkdown( + self::ASYNC_FILE, + '2. Run Synchronous Calls Concurrently' ); - $snippet->addLocal('curlMulti', $fakeCurlMulti); - $snippet->addLocal('httpClient', $httpClient); + $snippet->addLocal('client', $client); $result = $snippet->invoke(); $this->assertEquals( diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md index d29a8c048b15..4d04e163022d 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md @@ -138,12 +138,76 @@ $eachPromise->promise()->wait(); printf("Published %d messages\n", $publishedCount); ``` +### Paginating Concurrently + +For a single list query, async pagination is no faster than synchronous `foreach` iteration because +each page requires the `nextPageToken` returned by the previous page. Async pagination is useful +when listing across **multiple parents** (such as projects or regions) concurrently, or when +overlapping page fetches with per-item async RPCs. + +Inside a `.then()` callback, iterate `$response->getPage()` (the current page only) rather than +`$response` directly—iterating `$response` calls `Page::getNextPage()`, which blocks synchronously +via `wait()`—and chain the next `*Async()` call using `$page->getNextPageToken()`: + +```php +use Google\ApiCore\PagedListResponse; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use Google\Cloud\SecretManager\V1\ListSecretsRequest; +use GuzzleHttp\Promise\PromiseInterface; +use GuzzleHttp\Promise\Utils; + +function listAllSecretsAsync( + SecretManagerServiceClient $client, + string $parent, + string $pageToken = '', + array $secrets = [] +): PromiseInterface { + $request = (new ListSecretsRequest()) + ->setParent($parent) + ->setPageToken($pageToken); + + return $client->listSecretsAsync($request)->then( + function (PagedListResponse $response) use ($client, $parent, $secrets) { + // Iterate getPage() (current page only), NOT $response directly + $page = $response->getPage(); + foreach ($page as $secret) { + $secrets[] = $secret; + } + + if ($page->hasNextPage()) { + return listAllSecretsAsync( + $client, + $parent, + $page->getNextPageToken(), + $secrets + ); + } + + return $secrets; + } + ); +} + +$client = new SecretManagerServiceClient(); +$parents = ['projects/proj-a', 'projects/proj-b']; + +$promises = []; +foreach ($parents as $parent) { + $promises[$parent] = listAllSecretsAsync($client, $parent); +} + +$secretsByProject = Utils::unwrap($promises); +foreach ($secretsByProject as $parent => $secrets) { + printf("%s: %d secrets\n", $parent, count($secrets)); +} +``` + ## 2. Supported Call Types * **Unary (`PromiseInterface`):** Resolves to the protobuf response message. * **Paginated (`PromiseInterface`):** Resolves the first page asynchronously. - Iterating past the first page via `foreach` fetches subsequent pages synchronously; to paginate - asynchronously, pass `pageToken` explicitly to `*Async()`. + See [Paginating Concurrently](#paginating-concurrently) for fetching subsequent pages without + blocking. * **Long-Running Operation (`PromiseInterface`):** Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. * **Streaming & Resumable Uploads:** Not supported via `*Async()` (throws `ValidationException`). @@ -183,138 +247,90 @@ foreach ($objects as $name => $object) { ## 3. Using PHP Fibers with the REST Transport -PHP `Fiber`s allow you to write normal synchronous client code (such as -`$client->accessSecretVersion($request)`) that suspends the current fiber while waiting on network -I/O, letting other fibers run on the same thread without chaining `.then()` callbacks. +In Fiber-based applications (such as [AMPHP][amp]), you can run standard synchronous client methods +concurrently over the **`rest`** transport without chaining `.then()` callbacks by routing Guzzle +requests through [`amphp/http-client-guzzle-adapter`][amp-guzzle-adapter]: -Because PHP `Fiber`s do not include a built-in scheduler, you pair them with Guzzle's -`CurlMultiHandler` (or an event loop like [`revolt/event-loop`][revolt]) and pass a Fiber-aware -`httpHandler` and `authHttpHandler` to the **`rest`** transport. +```sh +composer require amphp/amp amphp/http-client-guzzle-adapter +``` > [!IMPORTANT] > Fiber suspension only works with `'transport' => 'rest'`. Under `'transport' => 'grpc'`, > synchronous client calls block inside the `grpc` C extension (`Grpc\UnaryCall::wait()`), which -> does not expose pollable sockets to PHP's userland event loop. For concurrent gRPC calls, use the +> does not expose pollable sockets to PHP's event loop. For concurrent gRPC calls, use the > `*Async()` methods shown in Section 1. -[revolt]: https://revolt.run/ +[amp]: https://amphp.org/ +[amp-guzzle-adapter]: https://github.com/amphp/http-client-guzzle-adapter -### Driving Fibers with `CurlMultiHandler` +### 1. Configure the REST Client -The example below uses native PHP `Fiber`s and Guzzle's `CurlMultiHandler` with zero additional -dependencies. Configuring both `httpHandler` and `authHttpHandler` ensures that both API requests -and OAuth2 token refreshes suspend the active fiber rather than blocking the thread. +Build an HTTP handler around `GuzzleHandlerAdapter` with `HttpHandlerFactory::build()` and pass it +to both `credentialsConfig` (so OAuth2 token refreshes are non-blocking) and `transportConfig`: ```php -use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter; +use Google\Auth\HttpHandler\HttpHandlerFactory; use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; use GuzzleHttp\Client; -use GuzzleHttp\Handler\CurlMultiHandler; use GuzzleHttp\HandlerStack; -use GuzzleHttp\Promise\Promise; -use GuzzleHttp\Promise\PromiseInterface; -use GuzzleHttp\Promise\Utils; -use Psr\Http\Message\RequestInterface; -use Psr\Http\Message\ResponseInterface; - -$curlMulti = new CurlMultiHandler(['select_timeout' => 0.01]); -$httpClient = new Client(['handler' => HandlerStack::create($curlMulti)]); - -// Suspends the current Fiber until Guzzle resolves the HTTP transfer -$asyncFiberHandler = function ( - RequestInterface $request, - array $options = [] -) use ($httpClient): PromiseInterface { - $guzzlePromise = $httpClient->sendAsync($request, $options); - $fiber = Fiber::getCurrent(); - if ($fiber === null) { - return $guzzlePromise; - } - return $promise = new Promise(function () use (&$promise, $guzzlePromise, $fiber) { - $guzzlePromise->then( - static fn () => $fiber->isSuspended() && $fiber->resume(), - static fn () => $fiber->isSuspended() && $fiber->resume() - ); - if ($guzzlePromise->getState() === PromiseInterface::PENDING) { - Fiber::suspend(); - } - try { - $promise->resolve($guzzlePromise->wait()); - } catch (\Throwable $e) { - $promise->reject($e); - } - }); -}; - -// Wraps the async handler for synchronous OAuth2 token fetches in google/auth -$syncFiberHandler = static fn ( - RequestInterface $request, - array $options = [] -): ResponseInterface => $asyncFiberHandler($request, $options)->wait(); +// Route Guzzle requests through AMPHP's Fiber-native HTTP client +$httpClient = new Client([ + 'handler' => HandlerStack::create(new GuzzleHandlerAdapter()), +]); +$httpHandler = HttpHandlerFactory::build($httpClient); +// Configure both auth token refreshes and REST calls to use the handler $client = new SecretManagerServiceClient([ 'transport' => 'rest', 'credentialsConfig' => [ - 'authHttpHandler' => $syncFiberHandler, + 'authHttpHandler' => $httpHandler, ], 'transportConfig' => [ 'rest' => [ - 'httpHandler' => $asyncFiberHandler, + 'httpHandler' => [$httpHandler, 'async'], ], ], ]); +``` + +### 2. Run Synchronous Calls Concurrently + +With the Fiber-backed handler configured, standard synchronous methods (including `foreach` +pagination across pages) automatically suspend the current Fiber while waiting on HTTP I/O: + +```php +use Amp\Future; +use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; +use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; +use function Amp\async; $secretIds = ['db-password', 'api-key', 'jwt-signing-key']; -$fibers = []; +$futures = []; foreach ($secretIds as $secretId) { - $fiber = new Fiber(function () use ($client, $secretId): string { - $request = (new AccessSecretVersionRequest())->setName( - SecretManagerServiceClient::secretVersionName('my-project', $secretId, 'latest') + $futures[$secretId] = async(function () use ($client, $secretId): string { + $versionName = SecretManagerServiceClient::secretVersionName( + 'my-project', + $secretId, + 'latest' ); + $request = (new AccessSecretVersionRequest())->setName($versionName); - // Synchronous method call—suspends this Fiber while HTTP I/O is in flight - $response = $client->accessSecretVersion($request); - return $response->getPayload()->getData(); + // Suspends the current Fiber automatically while waiting on HTTP I/O + return $client->accessSecretVersion($request)->getPayload()->getData(); }); - $fiber->start(); - $fibers[$secretId] = $fiber; } -// Tick Guzzle's curl_multi loop until all fibers complete -while (array_filter($fibers, static fn (Fiber $f) => !$f->isTerminated())) { - $curlMulti->tick(); - Utils::queue()->run(); +// Wait for all Fibers to finish and collect their return values +$secrets = Future\await($futures); +foreach ($secrets as $secretId => $value) { + printf("%s: %s\n", $secretId, $value); } - -foreach ($fibers as $secretId => $fiber) { - printf("%s: %s\n", $secretId, $fiber->getReturn()); -} -``` - -### Integrating with an Event Loop (`revolt/event-loop` / Amp) - -In long-running async applications built on [`revolt/event-loop`][revolt] or [`amphp/amp`][amp], -register a periodic timer on the event loop to tick `CurlMultiHandler` while requests are active -instead of writing a manual `while` loop: - -```php -use Revolt\EventLoop; -use GuzzleHttp\Promise\Utils; - -// Register a periodic callback to advance cURL transfers on the Revolt loop -$timerId = EventLoop::repeat(0.01, static function () use ($curlMulti): void { - $curlMulti->tick(); - Utils::queue()->run(); -}); - -// Unreference the timer so it does not keep the process alive once work finishes -EventLoop::unreference($timerId); ``` -[amp]: https://amphp.org/ - > [!NOTE] > Built-in client retries sleep via `usleep()` between attempts, which pauses the current thread > during backoff. In latency-sensitive event-loop servers, consider setting From 72aca736c56ddf803eed61529e720787d54ccf95 Mon Sep 17 00:00:00 2001 From: Brent Shaffer Date: Thu, 12 Nov 2026 21:27:35 +0000 Subject: [PATCH 4/5] docs: restore Supported Call Types table and simplify pagination note --- ASYNC.md | 78 ++----------------- .../ProductNeutralGuides/AsyncTest.php | 72 ----------------- .../docfx/ProductNeutralGuides/async.md | 78 ++----------------- 3 files changed, 12 insertions(+), 216 deletions(-) diff --git a/ASYNC.md b/ASYNC.md index 4d04e163022d..644524c10955 100644 --- a/ASYNC.md +++ b/ASYNC.md @@ -138,80 +138,14 @@ $eachPromise->promise()->wait(); printf("Published %d messages\n", $publishedCount); ``` -### Paginating Concurrently - -For a single list query, async pagination is no faster than synchronous `foreach` iteration because -each page requires the `nextPageToken` returned by the previous page. Async pagination is useful -when listing across **multiple parents** (such as projects or regions) concurrently, or when -overlapping page fetches with per-item async RPCs. - -Inside a `.then()` callback, iterate `$response->getPage()` (the current page only) rather than -`$response` directly—iterating `$response` calls `Page::getNextPage()`, which blocks synchronously -via `wait()`—and chain the next `*Async()` call using `$page->getNextPageToken()`: - -```php -use Google\ApiCore\PagedListResponse; -use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; -use Google\Cloud\SecretManager\V1\ListSecretsRequest; -use GuzzleHttp\Promise\PromiseInterface; -use GuzzleHttp\Promise\Utils; - -function listAllSecretsAsync( - SecretManagerServiceClient $client, - string $parent, - string $pageToken = '', - array $secrets = [] -): PromiseInterface { - $request = (new ListSecretsRequest()) - ->setParent($parent) - ->setPageToken($pageToken); - - return $client->listSecretsAsync($request)->then( - function (PagedListResponse $response) use ($client, $parent, $secrets) { - // Iterate getPage() (current page only), NOT $response directly - $page = $response->getPage(); - foreach ($page as $secret) { - $secrets[] = $secret; - } - - if ($page->hasNextPage()) { - return listAllSecretsAsync( - $client, - $parent, - $page->getNextPageToken(), - $secrets - ); - } - - return $secrets; - } - ); -} - -$client = new SecretManagerServiceClient(); -$parents = ['projects/proj-a', 'projects/proj-b']; - -$promises = []; -foreach ($parents as $parent) { - $promises[$parent] = listAllSecretsAsync($client, $parent); -} - -$secretsByProject = Utils::unwrap($promises); -foreach ($secretsByProject as $parent => $secrets) { - printf("%s: %d secrets\n", $parent, count($secrets)); -} -``` - ## 2. Supported Call Types -* **Unary (`PromiseInterface`):** Resolves to the protobuf response message. -* **Paginated (`PromiseInterface`):** Resolves the first page asynchronously. - See [Paginating Concurrently](#paginating-concurrently) for fetching subsequent pages without - blocking. -* **Long-Running Operation (`PromiseInterface`):** Resolves once the server - *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. -* **Streaming & Resumable Uploads:** Not supported via `*Async()` (throws `ValidationException`). - Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. +| Call Type | `*Async()` Return Type | Behavior | +| :--- | :--- | :--- | +| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | +| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `$response->getPage()->getNextPageToken()` via `setPageToken()` to another `*Async()` call. | +| **Long-Running Operation** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. | +| **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | [core-concepts]: https://docs.cloud.google.com/php/docs/reference/help/core_concepts diff --git a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php index 6735c466dc6a..7e61fe08630a 100644 --- a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php +++ b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php @@ -31,9 +31,6 @@ use Google\Cloud\PubSub\V1\PublishResponse; use Google\Cloud\SecretManager\V1\AccessSecretVersionResponse; use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; -use Google\Cloud\SecretManager\V1\ListSecretsRequest; -use Google\Cloud\SecretManager\V1\ListSecretsResponse; -use Google\Cloud\SecretManager\V1\Secret; use Google\Cloud\SecretManager\V1\SecretPayload; use Google\Cloud\Storage\Bucket; use Google\Cloud\Storage\StorageClient; @@ -191,75 +188,6 @@ public function testLimitingConcurrency() $this->assertEquals("Published 5 messages\n", $result->output()); } - public function testPaginatingConcurrently() - { - $snippet = $this->snippetFromMarkdown( - self::ASYNC_FILE, - 'Paginating Concurrently' - ); - - $transport = $this->prophesize(TransportInterface::class); - $transport->startUnaryCall(Argument::type(Call::class), Argument::type('array')) - ->shouldBeCalledTimes(3) - ->will(function (array $args) { - /** @var Call $call */ - $call = $args[0]; - /** @var ListSecretsRequest $request */ - $request = $call->getMessage(); - $parent = $request->getParent(); - $token = $request->getPageToken(); - - if ($parent === 'projects/proj-a' && $token === '') { - return Create::promiseFor( - (new ListSecretsResponse()) - ->setSecrets([ - (new Secret())->setName('projects/proj-a/secrets/s1'), - (new Secret())->setName('projects/proj-a/secrets/s2'), - ]) - ->setNextPageToken('page-2') - ); - } - - if ($parent === 'projects/proj-a' && $token === 'page-2') { - return Create::promiseFor( - (new ListSecretsResponse()) - ->setSecrets([ - (new Secret())->setName('projects/proj-a/secrets/s3'), - ]) - ); - } - - return Create::promiseFor( - (new ListSecretsResponse()) - ->setSecrets([ - (new Secret())->setName('projects/proj-b/secrets/s1'), - ]) - ); - }); - - $client = new SecretManagerServiceClient([ - 'credentials' => new InsecureCredentialsWrapper(), - 'transport' => $transport->reveal(), - ]); - - $snippet->replace( - '$client = new SecretManagerServiceClient();', - 'global $testClient; $client = $testClient;' - ); - global $testClient; - $testClient = $client; - - $result = $snippet->invoke(); - $this->assertEquals( - <<<'EOF' -projects/proj-a: 3 secrets -projects/proj-b: 1 secrets - -EOF, - $result->output() - ); - } - public function testHandwrittenClientHelpers() { $snippet = $this->snippetFromMarkdown( diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md index 4d04e163022d..644524c10955 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md @@ -138,80 +138,14 @@ $eachPromise->promise()->wait(); printf("Published %d messages\n", $publishedCount); ``` -### Paginating Concurrently - -For a single list query, async pagination is no faster than synchronous `foreach` iteration because -each page requires the `nextPageToken` returned by the previous page. Async pagination is useful -when listing across **multiple parents** (such as projects or regions) concurrently, or when -overlapping page fetches with per-item async RPCs. - -Inside a `.then()` callback, iterate `$response->getPage()` (the current page only) rather than -`$response` directly—iterating `$response` calls `Page::getNextPage()`, which blocks synchronously -via `wait()`—and chain the next `*Async()` call using `$page->getNextPageToken()`: - -```php -use Google\ApiCore\PagedListResponse; -use Google\Cloud\SecretManager\V1\Client\SecretManagerServiceClient; -use Google\Cloud\SecretManager\V1\ListSecretsRequest; -use GuzzleHttp\Promise\PromiseInterface; -use GuzzleHttp\Promise\Utils; - -function listAllSecretsAsync( - SecretManagerServiceClient $client, - string $parent, - string $pageToken = '', - array $secrets = [] -): PromiseInterface { - $request = (new ListSecretsRequest()) - ->setParent($parent) - ->setPageToken($pageToken); - - return $client->listSecretsAsync($request)->then( - function (PagedListResponse $response) use ($client, $parent, $secrets) { - // Iterate getPage() (current page only), NOT $response directly - $page = $response->getPage(); - foreach ($page as $secret) { - $secrets[] = $secret; - } - - if ($page->hasNextPage()) { - return listAllSecretsAsync( - $client, - $parent, - $page->getNextPageToken(), - $secrets - ); - } - - return $secrets; - } - ); -} - -$client = new SecretManagerServiceClient(); -$parents = ['projects/proj-a', 'projects/proj-b']; - -$promises = []; -foreach ($parents as $parent) { - $promises[$parent] = listAllSecretsAsync($client, $parent); -} - -$secretsByProject = Utils::unwrap($promises); -foreach ($secretsByProject as $parent => $secrets) { - printf("%s: %d secrets\n", $parent, count($secrets)); -} -``` - ## 2. Supported Call Types -* **Unary (`PromiseInterface`):** Resolves to the protobuf response message. -* **Paginated (`PromiseInterface`):** Resolves the first page asynchronously. - See [Paginating Concurrently](#paginating-concurrently) for fetching subsequent pages without - blocking. -* **Long-Running Operation (`PromiseInterface`):** Resolves once the server - *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. -* **Streaming & Resumable Uploads:** Not supported via `*Async()` (throws `ValidationException`). - Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. +| Call Type | `*Async()` Return Type | Behavior | +| :--- | :--- | :--- | +| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | +| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `$response->getPage()->getNextPageToken()` via `setPageToken()` to another `*Async()` call. | +| **Long-Running Operation** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. | +| **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | [core-concepts]: https://docs.cloud.google.com/php/docs/reference/help/core_concepts From 5f7cf6cb8ca16a1bca783bc26885dd6ebeb11ed2 Mon Sep 17 00:00:00 2001 From: Brent Shaffer Date: Fri, 20 Nov 2026 21:55:07 +0000 Subject: [PATCH 5/5] docs: qualify Guzzle classes and methods in ASYNC.md --- ASYNC.md | 39 +++++++++++-------- .../ProductNeutralGuides/AsyncTest.php | 6 +-- .../docfx/ProductNeutralGuides/async.md | 39 +++++++++++-------- 3 files changed, 47 insertions(+), 37 deletions(-) diff --git a/ASYNC.md b/ASYNC.md index 644524c10955..73a93b50de7a 100644 --- a/ASYNC.md +++ b/ASYNC.md @@ -10,17 +10,18 @@ multiple API calls concurrently over **both gRPC and REST**. immediately dispatches the RPC onto the `grpc` C extension's background network threads over multiplexed HTTP/2 streams. * **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's - `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. + `GuzzleHttp\Handler\CurlMultiHandler`, multiplexing concurrent transfers on a single thread via + `curl_multi`. [guzzle-promises]: https://github.com/guzzle/promises -## 1. Concurrent Requests with Promises +## 1. Concurrent Requests with Guzzle Promises -### Waiting on Multiple Requests (`Utils::unwrap`) +### Waiting on Multiple Requests (`GuzzleHttp\Promise\Utils::unwrap`) Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently -and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` -throws a `Google\ApiCore\ApiException` immediately. +and return their responses keyed by the same array keys. If any request fails, +`GuzzleHttp\Promise\Utils::unwrap()` throws a `Google\ApiCore\ApiException` immediately. ```php use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; @@ -55,11 +56,12 @@ foreach ($responses as $secretId => $response) { } ``` -### Handling Partial Failures (`Utils::settle`) +### Handling Partial Failures (`GuzzleHttp\Promise\Utils::settle`) -When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. -Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or -`PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. +When individual requests are allowed to fail without aborting the batch, use +`GuzzleHttp\Promise\Utils::settle()`. Each entry in the settled array contains `'state'` +(`GuzzleHttp\Promise\PromiseInterface::FULFILLED` or +`GuzzleHttp\Promise\PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. ```php use Google\ApiCore\ApiException; @@ -96,7 +98,7 @@ foreach ($results as $key => $result) { } ``` -### Limiting Concurrency (`EachPromise`) +### Limiting Concurrency (`GuzzleHttp\Promise\EachPromise`) Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive concurrent streams or hits API rate limits. Yield promises lazily from a generator into @@ -142,9 +144,9 @@ printf("Published %d messages\n", $publishedCount); | Call Type | `*Async()` Return Type | Behavior | | :--- | :--- | :--- | -| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | -| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `$response->getPage()->getNextPageToken()` via `setPageToken()` to another `*Async()` call. | -| **Long-Running Operation** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. | +| **Unary** | `GuzzleHttp\Promise\PromiseInterface` | Resolves to the protobuf response message. | +| **Paginated** | `GuzzleHttp\Promise\PromiseInterface` | Resolves the first page asynchronously. Iterating via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `$response->getPage()->getNextPageToken()` via `setPageToken()` to another `*Async()` call. | +| **Long-Running Operation** | `GuzzleHttp\Promise\PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. | | **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | [core-concepts]: https://docs.cloud.google.com/php/docs/reference/help/core_concepts @@ -182,8 +184,9 @@ foreach ($objects as $name => $object) { ## 3. Using PHP Fibers with the REST Transport In Fiber-based applications (such as [AMPHP][amp]), you can run standard synchronous client methods -concurrently over the **`rest`** transport without chaining `.then()` callbacks by routing Guzzle -requests through [`amphp/http-client-guzzle-adapter`][amp-guzzle-adapter]: +concurrently over the **`rest`** transport without chaining +`GuzzleHttp\Promise\PromiseInterface::then()` callbacks by routing Guzzle requests through +[`amphp/http-client-guzzle-adapter`][amp-guzzle-adapter]: ```sh composer require amphp/amp amphp/http-client-guzzle-adapter @@ -200,8 +203,10 @@ composer require amphp/amp amphp/http-client-guzzle-adapter ### 1. Configure the REST Client -Build an HTTP handler around `GuzzleHandlerAdapter` with `HttpHandlerFactory::build()` and pass it -to both `credentialsConfig` (so OAuth2 token refreshes are non-blocking) and `transportConfig`: +Build an HTTP handler around a `GuzzleHttp\Client` backed by +`Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter` using +`Google\Auth\HttpHandler\HttpHandlerFactory::build()`, and pass it to both `credentialsConfig` +(so OAuth2 token refreshes are non-blocking) and `transportConfig`: ```php use Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter; diff --git a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php index 7e61fe08630a..c23aec0d8129 100644 --- a/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php +++ b/dev/tests/Snippet/ProductNeutralGuides/AsyncTest.php @@ -63,7 +63,7 @@ public function testWaitingOnMultipleRequests() { $snippet = $this->snippetFromMarkdown( self::ASYNC_FILE, - 'Waiting on Multiple Requests (`Utils::unwrap`)' + 'Waiting on Multiple Requests (`GuzzleHttp\Promise\Utils::unwrap`)' ); $transport = $this->prophesize(TransportInterface::class); @@ -112,7 +112,7 @@ public function testHandlingPartialFailures() { $snippet = $this->snippetFromMarkdown( self::ASYNC_FILE, - 'Handling Partial Failures (`Utils::settle`)' + 'Handling Partial Failures (`GuzzleHttp\Promise\Utils::settle`)' ); $transport = $this->prophesize(TransportInterface::class); @@ -156,7 +156,7 @@ public function testLimitingConcurrency() { $snippet = $this->snippetFromMarkdown( self::ASYNC_FILE, - 'Limiting Concurrency (`EachPromise`)' + 'Limiting Concurrency (`GuzzleHttp\Promise\EachPromise`)' ); $inFlight = 0; diff --git a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md index 644524c10955..73a93b50de7a 100644 --- a/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md +++ b/dev/tests/fixtures/docfx/ProductNeutralGuides/async.md @@ -10,17 +10,18 @@ multiple API calls concurrently over **both gRPC and REST**. immediately dispatches the RPC onto the `grpc` C extension's background network threads over multiplexed HTTP/2 streams. * **REST (`'transport' => 'rest'`):** Calling `*Async()` registers the HTTP request with Guzzle's - `CurlMultiHandler`, multiplexing concurrent transfers on a single thread via `curl_multi`. + `GuzzleHttp\Handler\CurlMultiHandler`, multiplexing concurrent transfers on a single thread via + `curl_multi`. [guzzle-promises]: https://github.com/guzzle/promises -## 1. Concurrent Requests with Promises +## 1. Concurrent Requests with Guzzle Promises -### Waiting on Multiple Requests (`Utils::unwrap`) +### Waiting on Multiple Requests (`GuzzleHttp\Promise\Utils::unwrap`) Use `GuzzleHttp\Promise\Utils::unwrap()` to execute an array of `*Async()` promises concurrently -and return their responses keyed by the same array keys. If any request fails, `Utils::unwrap()` -throws a `Google\ApiCore\ApiException` immediately. +and return their responses keyed by the same array keys. If any request fails, +`GuzzleHttp\Promise\Utils::unwrap()` throws a `Google\ApiCore\ApiException` immediately. ```php use Google\Cloud\SecretManager\V1\AccessSecretVersionRequest; @@ -55,11 +56,12 @@ foreach ($responses as $secretId => $response) { } ``` -### Handling Partial Failures (`Utils::settle`) +### Handling Partial Failures (`GuzzleHttp\Promise\Utils::settle`) -When individual requests are allowed to fail without aborting the batch, use `Utils::settle()`. -Each entry in the settled array contains `'state'` (`PromiseInterface::FULFILLED` or -`PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. +When individual requests are allowed to fail without aborting the batch, use +`GuzzleHttp\Promise\Utils::settle()`. Each entry in the settled array contains `'state'` +(`GuzzleHttp\Promise\PromiseInterface::FULFILLED` or +`GuzzleHttp\Promise\PromiseInterface::REJECTED`) along with either `'value'` or `'reason'`. ```php use Google\ApiCore\ApiException; @@ -96,7 +98,7 @@ foreach ($results as $key => $result) { } ``` -### Limiting Concurrency (`EachPromise`) +### Limiting Concurrency (`GuzzleHttp\Promise\EachPromise`) Avoid creating thousands of `*Async()` promises up front in a loop, which opens excessive concurrent streams or hits API rate limits. Yield promises lazily from a generator into @@ -142,9 +144,9 @@ printf("Published %d messages\n", $publishedCount); | Call Type | `*Async()` Return Type | Behavior | | :--- | :--- | :--- | -| **Unary** | `PromiseInterface` | Resolves to the protobuf response message. | -| **Paginated** | `PromiseInterface` | Resolves the first page asynchronously. Iterating via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `$response->getPage()->getNextPageToken()` via `setPageToken()` to another `*Async()` call. | -| **Long-Running Operation** | `PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. | +| **Unary** | `GuzzleHttp\Promise\PromiseInterface` | Resolves to the protobuf response message. | +| **Paginated** | `GuzzleHttp\Promise\PromiseInterface` | Resolves the first page asynchronously. Iterating via `foreach` fetches subsequent pages synchronously; to paginate asynchronously, pass `$response->getPage()->getNextPageToken()` via `setPageToken()` to another `*Async()` call. | +| **Long-Running Operation** | `GuzzleHttp\Promise\PromiseInterface` | Resolves once the server *starts* the operation. See [Core Concepts][core-concepts] for polling LROs. | | **Streaming & Resumable Uploads** | *Not supported* | Throws `ValidationException`. Use streaming methods (`ServerStream`, `ClientStream`, `BidiStream`) directly. | [core-concepts]: https://docs.cloud.google.com/php/docs/reference/help/core_concepts @@ -182,8 +184,9 @@ foreach ($objects as $name => $object) { ## 3. Using PHP Fibers with the REST Transport In Fiber-based applications (such as [AMPHP][amp]), you can run standard synchronous client methods -concurrently over the **`rest`** transport without chaining `.then()` callbacks by routing Guzzle -requests through [`amphp/http-client-guzzle-adapter`][amp-guzzle-adapter]: +concurrently over the **`rest`** transport without chaining +`GuzzleHttp\Promise\PromiseInterface::then()` callbacks by routing Guzzle requests through +[`amphp/http-client-guzzle-adapter`][amp-guzzle-adapter]: ```sh composer require amphp/amp amphp/http-client-guzzle-adapter @@ -200,8 +203,10 @@ composer require amphp/amp amphp/http-client-guzzle-adapter ### 1. Configure the REST Client -Build an HTTP handler around `GuzzleHandlerAdapter` with `HttpHandlerFactory::build()` and pass it -to both `credentialsConfig` (so OAuth2 token refreshes are non-blocking) and `transportConfig`: +Build an HTTP handler around a `GuzzleHttp\Client` backed by +`Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter` using +`Google\Auth\HttpHandler\HttpHandlerFactory::build()`, and pass it to both `credentialsConfig` +(so OAuth2 token refreshes are non-blocking) and `transportConfig`: ```php use Amp\Http\Client\GuzzleAdapter\GuzzleHandlerAdapter;