From f7018917347c6cba7d378fbe964c859524f7e994 Mon Sep 17 00:00:00 2001
From: ADmad <admad.coder@gmail.com>
Date: Sat, 18 Nov 2023 19:01:48 +0530
Subject: [PATCH] Add info about HTTP client events.

Refs cakephp/cakephp#17416
---
 en/core-libraries/httpclient.rst | 53 ++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/en/core-libraries/httpclient.rst b/en/core-libraries/httpclient.rst
index 514568a4be..8c66cc20fa 100644
--- a/en/core-libraries/httpclient.rst
+++ b/en/core-libraries/httpclient.rst
@@ -479,6 +479,59 @@ instead. You can force select a transport adapter using a constructor option::
 
     $client = new Client(['adapter' => Stream::class]);
 
+Events
+======
+
+The HTTP client triggers couple of events before and after sending a request
+which allows you to modify either the request or response or do other tasks like
+caching, logging etc.
+
+HttpClient.beforeSend
+---------------------
+
+    // Somewhere before calling one of the HTTP client's methods which makes a request
+    $http->getEventManager()->on(
+        'HttpClient.beforeSend',
+        function (
+            \Cake\Http\Client\ClientEvent $event,
+            \Cake\Http\Client\Request $request,
+            array $adapterOptions,
+            int $redirects
+        ) {
+            // Modify the request
+            $event->setRequest(....);
+            // Modify the adapter options
+            $event->setAdapterOptions(....);
+
+            // Skip making the actual request by returning a response.
+            // You can use $event->setResult($response) to achieve the same.
+            return new \Cake\Http\Client\Response(body: 'something');
+        }
+    );
+
+HttpClient.afterSend
+---------------------
+
+    // Somewhere before calling one of the HTTP client's methods which makes a request
+    $http->getEventManager()->on(
+        'HttpClient.afterSend',
+        function (
+            \Cake\Http\Client\ClientEvent $event,
+            \Cake\Http\Client\Request $request,
+            array $adapterOptions,
+            int $redirects,
+            bool $requestSent // Indicates whether the request was actually sent
+                              // or response returned from ``beforeSend`` event
+        ) {
+            // Get the response
+            $response = $event->getResponse();
+
+            // Return a new/modified response.
+            // You can use $event->setResult($response) to achieve the same.
+            return new \Cake\Http\Client\Response(body: 'something');
+        }
+    );
+
 .. _httpclient-testing:
 
 Testing