From 68765a402f45855cdf01d54a5744aee7532b4a54 Mon Sep 17 00:00:00 2001 From: Wendell Adriel Date: Tue, 30 Sep 2025 18:22:51 +0100 Subject: [PATCH 1/3] Add docs for Http::batch --- http-client.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/http-client.md b/http-client.md index 57e1cfe0f8..6e8ee246b3 100644 --- a/http-client.md +++ b/http-client.md @@ -500,6 +500,9 @@ public function boot(): void Sometimes, you may wish to make multiple HTTP requests concurrently. In other words, you want several requests to be dispatched at the same time instead of issuing the requests sequentially. This can lead to substantial performance improvements when interacting with slow HTTP APIs. + +### HTTP Pool + Thankfully, you may accomplish this using the `pool` method. The `pool` method accepts a closure which receives an `Illuminate\Http\Client\Pool` instance, allowing you to easily add requests to the request pool for dispatching: ```php @@ -552,6 +555,71 @@ $responses = Http::pool(fn (Pool $pool) => [ ]); ``` + +### HTTP Batch + +Another way of working with concurrent requests in Laravel is with the `batch` method. Like the `pool` method, it accepts a closure which receives an `Illuminate\Http\Client\Batch` instance, allowing you to easily add requests to the request pool for dispatching, but it also allows to define completion callbacks similar to the ones in `Bus::batch`: + +```php +use Illuminate\Http\Client\Batch; +use Illuminate\Http\Client\RequestException; +use Illuminate\Http\Client\Response; +use Illuminate\Support\Facades\Http; + +$responses = Http::batch(fn (Batch $batch) => [ + $batch->get('http://localhost/first'), + $batch->get('http://localhost/second'), + $batch->get('http://localhost/third'), +])->before(function (Batch $batch) { + // This runs before the first HTTP request is executed. +})->progress(function (Batch $batch, int|string $key, Response $response) { + // This runs after each successful HTTP request from the Batch. +})->catch(function (Batch $batch, int|string $key, Response|RequestException $response) { + // This runs after each failed HTTP request from the Batch. +})->then(function (Batch $batch, array $results) { + // This runs ONLY IF all the HTTP requests from the Batch are successful and the batch is not cancelled. +})->finally(function (Batch $batch, array $results) { + // This runs after all the HTTP requests from the Batch finish and the batch is not cancelled. +})->send(); +``` + +Also like the `pool` method, you can use the `as` method to name your requests: + +```php +$responses = Http::batch(fn (Batch $batch) => [ + $batch->as('first')->get('http://localhost/first'), + $batch->as('second')->get('http://localhost/second'), + $batch->as('third')->get('http://localhost/third'), +])->send(); +``` + +After a `batch` is started by calling the `send` method, you can't add new requests to it. Trying to do it will result in a `Illuminate\Http\Client\BatchInProgressException` exception being thrown. + + +#### Inspecting Batches + +The `Illuminate\Http\Client\Batch` instance that is provided to batch completion callbacks has a variety of properties and methods to assist you in interacting with and inspecting a given batch of requests: + +```php +// The total number of requests that belong to the batch. +$batch->totalRequests; + +// The total number of requests that are still pending. +$batch->pendingRequests; + +// The total number of requests that have failed. +$batch->failedRequests; + +// The total number of requests that have been processed by the batch thus far. +$batch->processedRequests(); + +// Indicates if the batch has finished executing. +$batch->finished(); + +// Indicates if the batch has job failures. +$batch->hasFailures(); +``` + ## Macros From ee426ac5e306d3cde4557410a9b887de04481306 Mon Sep 17 00:00:00 2001 From: Wendell Adriel Date: Tue, 30 Sep 2025 18:49:55 +0100 Subject: [PATCH 2/3] Code Review changes --- http-client.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/http-client.md b/http-client.md index 6e8ee246b3..8e67266452 100644 --- a/http-client.md +++ b/http-client.md @@ -571,15 +571,15 @@ $responses = Http::batch(fn (Batch $batch) => [ $batch->get('http://localhost/second'), $batch->get('http://localhost/third'), ])->before(function (Batch $batch) { - // This runs before the first HTTP request is executed. + // The batch has been created but no requests have been initialized... })->progress(function (Batch $batch, int|string $key, Response $response) { - // This runs after each successful HTTP request from the Batch. -})->catch(function (Batch $batch, int|string $key, Response|RequestException $response) { - // This runs after each failed HTTP request from the Batch. + // A single request has completed successfully... })->then(function (Batch $batch, array $results) { - // This runs ONLY IF all the HTTP requests from the Batch are successful and the batch is not cancelled. + // All requests completed successfully... +})->catch(function (Batch $batch, int|string $key, Response|RequestException $response) { + // First batch request failure detected... })->finally(function (Batch $batch, array $results) { - // This runs after all the HTTP requests from the Batch finish and the batch is not cancelled. + // The batch has finished executing... })->send(); ``` @@ -601,22 +601,22 @@ After a `batch` is started by calling the `send` method, you can't add new reque The `Illuminate\Http\Client\Batch` instance that is provided to batch completion callbacks has a variety of properties and methods to assist you in interacting with and inspecting a given batch of requests: ```php -// The total number of requests that belong to the batch. +// The number of requests assigned to the batch... $batch->totalRequests; -// The total number of requests that are still pending. +// The number of requests that have not been processed yet... $batch->pendingRequests; -// The total number of requests that have failed. +// The number of requests that have failed... $batch->failedRequests; -// The total number of requests that have been processed by the batch thus far. +// The number of requests that have been processed thus far... $batch->processedRequests(); -// Indicates if the batch has finished executing. +// Indicates if the batch has finished executing... $batch->finished(); -// Indicates if the batch has job failures. +// Indicates if the batch has request failures... $batch->hasFailures(); ``` From 409b1545cf2752cf960219bf992eb46ff3f08766 Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Wed, 1 Oct 2025 11:40:27 +0100 Subject: [PATCH 3/3] formatting --- http-client.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/http-client.md b/http-client.md index 8e67266452..ba3a8b50a3 100644 --- a/http-client.md +++ b/http-client.md @@ -11,6 +11,8 @@ - [Guzzle Middleware](#guzzle-middleware) - [Guzzle Options](#guzzle-options) - [Concurrent Requests](#concurrent-requests) + - [Request Pooling](#request-pooling) + - [Request Batching](#request-batching) - [Macros](#macros) - [Testing](#testing) - [Faking Responses](#faking-responses) @@ -500,8 +502,8 @@ public function boot(): void Sometimes, you may wish to make multiple HTTP requests concurrently. In other words, you want several requests to be dispatched at the same time instead of issuing the requests sequentially. This can lead to substantial performance improvements when interacting with slow HTTP APIs. - -### HTTP Pool + +### Request Pooling Thankfully, you may accomplish this using the `pool` method. The `pool` method accepts a closure which receives an `Illuminate\Http\Client\Pool` instance, allowing you to easily add requests to the request pool for dispatching: @@ -555,10 +557,10 @@ $responses = Http::pool(fn (Pool $pool) => [ ]); ``` - -### HTTP Batch + +### Request Batching -Another way of working with concurrent requests in Laravel is with the `batch` method. Like the `pool` method, it accepts a closure which receives an `Illuminate\Http\Client\Batch` instance, allowing you to easily add requests to the request pool for dispatching, but it also allows to define completion callbacks similar to the ones in `Bus::batch`: +Another way of working with concurrent requests in Laravel is to use the `batch` method. Like the `pool` method, it accepts a closure which receives an `Illuminate\Http\Client\Batch` instance, allowing you to easily add requests to the request pool for dispatching, but it also allows you to define completion callbacks: ```php use Illuminate\Http\Client\Batch; @@ -573,7 +575,7 @@ $responses = Http::batch(fn (Batch $batch) => [ ])->before(function (Batch $batch) { // The batch has been created but no requests have been initialized... })->progress(function (Batch $batch, int|string $key, Response $response) { - // A single request has completed successfully... + // An individual request has completed successfully... })->then(function (Batch $batch, array $results) { // All requests completed successfully... })->catch(function (Batch $batch, int|string $key, Response|RequestException $response) { @@ -583,7 +585,7 @@ $responses = Http::batch(fn (Batch $batch) => [ })->send(); ``` -Also like the `pool` method, you can use the `as` method to name your requests: +Like the `pool` method, you can use the `as` method to name your requests: ```php $responses = Http::batch(fn (Batch $batch) => [ @@ -593,7 +595,7 @@ $responses = Http::batch(fn (Batch $batch) => [ ])->send(); ``` -After a `batch` is started by calling the `send` method, you can't add new requests to it. Trying to do it will result in a `Illuminate\Http\Client\BatchInProgressException` exception being thrown. +After a `batch` is started by calling the `send` method, you can't add new requests to it. Trying to do so will result in a `Illuminate\Http\Client\BatchInProgressException` exception being thrown. #### Inspecting Batches