[12.x] Add PendingRequest@withRequestContext()

src/Illuminate/Http/Client/ConnectionException.php

@@ -4,5 +4,10 @@
 
 class ConnectionException extends HttpClientException
 {
-    //
+    /**
+     * The context passed when creating the request.
+     *
+     * @var array<array-key, mixed>
+     */
+    public array $requestContext = [];
 }

src/Illuminate/Http/Client/PendingRequest.php

@@ -229,6 +229,13 @@ class PendingRequest
      */
     protected $truncateExceptionsAt = null;
 
+    /**
+     * The request context.
+     *
+     * @var array<array-key, mixed>
+     */
+    protected array $requestContext = [];
+
     /**
      * Create a new HTTP Client instance.
      *
@@ -362,6 +369,19 @@ public function bodyFormat(string $format)
         });
     }
 
+    /**
+     * Add contextual data to be attached to the Response.
+     *
+     * @param  array<array-key, mixed>  $requestContext
+     * @return $this
+     */
+    public function withRequestContext(array $requestContext)
+    {
+        $this->requestContext = array_merge_recursive($this->requestContext, $requestContext);
+
+        return $this;
+    }
+
     /**
      * Set the given query parameters in the request URI.
      *
@@ -1507,6 +1527,8 @@ public function mergeOptions(...$options)
     protected function newResponse($response)
     {
         return tap(new Response($response), function (Response $laravelResponse) {
+            $laravelResponse->setRequestContext($this->requestContext);
+
             if ($this->truncateExceptionsAt === null) {
                 return;
             }
@@ -1675,6 +1697,7 @@ public function dontTruncateExceptions()
     protected function marshalConnectionException(ConnectException $e)
     {
         $exception = new ConnectionException($e->getMessage(), 0, $e);
+        $exception->requestContext = $this->requestContext;
 
         $request = new Request($e->getRequest());
 

src/Illuminate/Http/Client/RequestException.php

@@ -34,6 +34,13 @@ class RequestException extends HttpClientException
      */
     public $hasBeenSummarized = false;
 
+    /**
+     * The context passed when creating the request.
+     *
+     * @var array<array-key, mixed>
+     */
+    public array $requestContext = [];
+
     /**
      * Create a new exception instance.
      *

src/Illuminate/Http/Client/Response.php

@@ -54,6 +54,13 @@ class Response implements ArrayAccess, Stringable
      */
     protected $truncateExceptionsAt = null;
 
+    /**
+     * Contextual data from the request.
+     *
+     * @var array<array-key, mixed>
+     */
+    protected array $requestContext = [];
+
     /**
      * Create a new response instance.
      *
@@ -64,6 +71,29 @@ public function __construct($response)
         $this->response = $response;
     }
 
+    /**
+     * Set the request's context.
+     *
+     * @param  array<array-key, mixed>  $context
+     * @return $this
+     */
+    public function setRequestContext(array $context)
+    {
+        $this->requestContext = $context;
+
+        return $this;
+    }
+
+    /**
+     * Get the context set on the request.
+     *
+     * @return array<array-key, mixed>
+     */
+    public function getRequestContext(): array
+    {
+        return $this->requestContext;
+    }
+
     /**
      * Get the body of the response.
      *
@@ -304,7 +334,12 @@ public function toPsrResponse()
     public function toException()
     {
         if ($this->failed()) {
-            return new RequestException($this, $this->truncateExceptionsAt);
+            return tap(
+                new RequestException($this, $this->truncateExceptionsAt),
+                function (RequestException $e) {
+                    $e->requestContext = $this->requestContext;
+                }
+            );
         }
     }
 

tests/Http/HttpClientTest.php

@@ -4183,6 +4183,58 @@ public function testBatchConcurrency(): void
         $this->assertSame(0, $batch->failedRequests);
     }
 
+    public function testResponseWithRequestContext()
+    {
+        $this->factory->fake(['https://laravel.com' => $this->factory::response('OK')]);
+
+        $pendingRequest = $this->factory->withRequestContext([
+            'name' => 'testResponseWithRequestContext',
+        ]);
+
+        $response = $pendingRequest->get('https://laravel.com');
+
+        $this->assertEquals(['name' => 'testResponseWithRequestContext'], $response->getRequestContext());
+    }
+
+    public function testRequestExceptionHasRequestContext()
+    {
+        $this->factory->fake(['https://laravel.com' => $this->factory::response('Oh no', 403)]);
+
+        $pendingRequest = $this->factory->withRequestContext(['name' => 'testRequestExceptionHasRequestContext']);
+
+        $response = $pendingRequest->get('https://laravel.com');
+
+        $e = null;
+        try {
+            $response->throw();
+        } catch (Exception $thrown) {
+            $e = $thrown;
+        }
+
+        if ($e === null) {
+            $this->fail('No exception was thrown');
+        }
+
+        $this->assertInstanceOf(RequestException::class, $e);
+        $this->assertSame(['name' => 'testRequestExceptionHasRequestContext'], $e->requestContext);
+    }
+
+    public function testConnectionExceptionHasRequestContext()
+    {
+        $this->factory->fake(['https://laravel.com' => $this->factory::failedConnection('This thang failed')]);
+
+        $pendingRequest = $this->factory->withRequestContext(['name' => 'testConnectionExceptionHasRequestContext']);
+
+        $e = null;
+        try {
+            $pendingRequest->get('https://laravel.com');
+        } catch (ConnectionException $exception) {
+            $e = $exception;
+        }
+
+        $this->assertEquals(['name' => 'testConnectionExceptionHasRequestContext'], $e->requestContext);
+    }
+
     public static function methodsReceivingArrayableDataProvider()
     {
         return [