Merge pull request #300 from EasyPost/hooks

feat: adds http request and response hooks

Author: Justintime50

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds new `RequestHook` and `ResponseHook` events. (un)subscribe to them with the new `subscribeToRequestHook`, `subscribeToResponseHook`, `unsubscribeFromRequestHook`, or `unsubscribeFromResponseHook` methods of an `EasyPostClient`
+
 ## v6.7.0 (2023-06-06)
 
 - Migrates carrier metadata to GA (now available via `client.carrierMetadata.retrieve`)

README.md

@@ -63,6 +63,26 @@ $boughtShipment = $client->shipment->buy($shipment->id, $shipment->lowestRate())
 echo $boughtShipment;
 ```
 
+### HTTP Hooks
+
+Users can subscribe to HTTP requests and responses via the `RequestHook` and `ResponseHook` objects. To do so, pass a function to the `subscribeToRequestHook` or `subscribeToResponseHook` methods of an `EasyPostClient` object:
+
+```php
+function customFunction($args)
+{
+    // Pass your code here, data about the request/response is contained within `$args`.
+    echo "Received a request with the status code of: " . $args['http_status'];
+}
+
+$client = new \EasyPost\EasyPostClient(getenv('EASYPOST_API_KEY'));
+
+$client->subscribeToResponseHook('customFunction');
+
+// Make your API calls here, your customFunction will trigger once a response is received
+```
+
+You can also unsubscribe your functions in a similar manner by using the `unsubscribeFromRequestHook` and `unsubscribeFromResponseHook` methods of a client object.
+
 ## Documentation
 
 API documentation can be found at: <https://easypost.com/docs/api>.

lib/EasyPost/EasyPostClient.php

@@ -5,6 +5,8 @@
 use EasyPost\Constant\Constants;
 use EasyPost\Exception\General\EasyPostException;
 use EasyPost\Exception\General\MissingParameterException;
+use EasyPost\Hook\RequestHook;
+use EasyPost\Hook\ResponseHook;
 use EasyPost\Service\AddressService;
 use EasyPost\Service\BaseService;
 use EasyPost\Service\BatchService;
@@ -65,6 +67,8 @@ class EasyPostClient extends BaseService
     private $timeout;
     private $apiBase;
     private $mockingUtility;
+    public $requestEvent;
+    public $responseEvent;
 
     /**
      * Constructor for an EasyPostClient.
@@ -85,6 +89,8 @@ public function __construct(
         $this->timeout = $timeout;
         $this->apiBase = $apiBase;
         $this->mockingUtility = $mockingUtility;
+        $this->requestEvent = new RequestHook();
+        $this->responseEvent = new ResponseHook();
 
         if (!$this->apiKey) {
             throw new MissingParameterException(
@@ -187,4 +193,48 @@ public function getMockingUtility()
     {
         return $this->mockingUtility;
     }
+
+    /**
+     * Subscribe functions to run when a request event occurs.
+     *
+     * @param callable $function
+     * @return void
+     */
+    public function subscribeToRequestHook($function)
+    {
+        $this->requestEvent->addHandler($function);
+    }
+
+    /**
+     * Unsubscribe functions from running when a request even occurs.
+     *
+     * @param callable $function
+     * @return void
+     */
+    public function unsubscribeFromRequestHook($function)
+    {
+        $this->requestEvent->removeHandler($function);
+    }
+
+    /**
+     * Subscribe functions to run when a response event occurs.
+     *
+     * @param callable $function
+     * @return void
+     */
+    public function subscribeToResponseHook($function)
+    {
+        $this->responseEvent->addHandler($function);
+    }
+
+    /**
+     * Unsubscribe functions from running when a response even occurs.
+     *
+     * @param callable $function
+     * @return void
+     */
+    public function unsubscribeFromResponseHook($function)
+    {
+        $this->responseEvent->removeHandler($function);
+    }
 }

lib/EasyPost/Hook/EventHook.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace EasyPost\Hook;
+
+/**
+ * The parent event that occurs when a hook is triggered.
+ */
+class EventHook
+{
+    private $eventHandlers = [];
+
+    public function __invoke(...$args)
+    {
+        foreach ($this->eventHandlers as $eventHandler) {
+            $eventHandler(...$args);
+        }
+    }
+
+    public function addHandler($handler)
+    {
+        $this->eventHandlers[] = $handler;
+        return $this;
+    }
+
+    public function removeHandler($handler)
+    {
+        $index = array_search($handler, $this->eventHandlers, true);
+        if ($index !== false) {
+            array_splice($this->eventHandlers, $index, 1);
+        }
+        return $this;
+    }
+}

lib/EasyPost/Hook/RequestHook.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace EasyPost\Hook;
+
+/**
+ * An event that gets triggered when an HTTP request begins.
+ */
+class RequestHook extends EventHook
+{
+}

lib/EasyPost/Hook/ResponseHook.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace EasyPost\Hook;
+
+/**
+ * An event that gets triggered when an HTTP response is returned.
+ */
+class ResponseHook extends EventHook
+{
+}

lib/EasyPost/Http/Requestor.php

@@ -2,6 +2,8 @@
 
 namespace EasyPost\Http;
 
+use DateTime;
+use DateTimeZone;
 use EasyPost\Constant\Constants;
 use EasyPost\EasyPostClient;
 use EasyPost\EasypostObject;
@@ -179,6 +181,18 @@ private static function requestRaw($client, $method, $url, $params, $beta = fals
             'User-Agent' => 'EasyPost/v2 PhpClient/' . Constants::LIBRARY_VERSION . " PHP/$phpVersion OS/$osType OSVersion/$osVersion OSArch/$osArch", // phpcs:ignore
         ];
 
+        $requestUuid = uniqid();
+        date_default_timezone_set('UTC');
+        $requestTimestamp = microtime(true);
+        ($client->requestEvent)([
+            'method' => $method,
+            'path' => $absoluteUrl,
+            'headers' => $headers,
+            'request_body' => $params,
+            'request_timestamp' => $requestTimestamp,
+            'request_uuid' => $requestUuid,
+        ]);
+
         if ($client->mock()) {
             // If there are mock requests set, this client will ONLY make mock requests
             $mockingUtility = $client->getMockingUtility();
@@ -189,26 +203,38 @@ private static function requestRaw($client, $method, $url, $params, $beta = fals
 
             $responseBody = $matchingRequest->responseInfo->body;
             $httpStatus = $matchingRequest->responseInfo->statusCode;
+            $responseHeaders = [];
+        } else {
+            $guzzleClient = new Client();
+            $requestOptions['headers'] = $headers;
+            try {
+                $response = $guzzleClient->request($method, $absoluteUrl, $requestOptions);
+            } catch (\GuzzleHttp\Exception\ConnectException $error) {
+                throw new HttpException(sprintf(Constants::COMMUNICATION_ERROR, 'EasyPost', $error->getMessage()));
+            }
 
-            return [$responseBody, $httpStatus];
-        }
-
-        $guzzleClient = new Client();
-        $requestOptions['headers'] = $headers;
-        try {
-            $response = $guzzleClient->request($method, $absoluteUrl, $requestOptions);
-        } catch (\GuzzleHttp\Exception\ConnectException $error) {
-            throw new HttpException(sprintf(Constants::COMMUNICATION_ERROR, 'EasyPost', $error->getMessage()));
-        }
+            // Guzzle does not have a native way of catching timeout exceptions...
+            // If we don't have a response at this point, it's likely due to a timeout.
+            if (!isset($response)) {
+                throw new TimeoutException(sprintf(Constants::NO_RESPONSE_ERROR, 'EasyPost'));
+            }
 
-        // Guzzle does not have a native way of catching timeout exceptions...
-        // If we don't have a response at this point, it's likely due to a timeout.
-        if (!isset($response)) {
-            throw new TimeoutException(sprintf(Constants::NO_RESPONSE_ERROR, 'EasyPost'));
+            $responseBody = $response->getBody();
+            $httpStatus = $response->getStatusCode();
+            $responseHeaders = $response->getHeaders();
         }
 
-        $responseBody = $response->getBody();
-        $httpStatus = $response->getStatusCode();
+        $responseTimestamp = microtime(true);
+        ($client->responseEvent)([
+            'http_status' => $httpStatus,
+            'method' => $method,
+            'path' => $absoluteUrl,
+            'headers' => $responseHeaders,
+            'response_body' => $responseBody,
+            'request_timestamp' => $requestTimestamp,
+            'response_timestamp' => $responseTimestamp,
+            'request_uuid' => $requestUuid,
+        ]);
 
         return [$responseBody, $httpStatus];
     }

test/EasyPost/HookTest.php

@@ -0,0 +1,101 @@
+<?php
+
+namespace EasyPost\Test;
+
+use DateTime;
+use EasyPost\EasyPostClient;
+
+class HookTest extends \PHPUnit\Framework\TestCase
+{
+    private static $client;
+
+    /**
+     * Setup the testing environment for this file.
+     */
+    public static function setUpBeforeClass(): void
+    {
+        TestUtil::setupVcrTests();
+        self::$client = new EasyPostClient(getenv('EASYPOST_TEST_API_KEY'));
+    }
+
+    /**
+     * Cleanup the testing environment once finished.
+     */
+    public static function tearDownAfterClass(): void
+    {
+        TestUtil::teardownVcrTests();
+    }
+
+    /**
+     * Make assertions about a request once the RequestHook fires.
+     */
+    public function requestTest($args)
+    {
+        $this->assertEquals('post', $args['method']);
+        $this->assertEquals('https://api.easypost.com/v2/parcels', $args['path']);
+        $this->assertArrayHasKey('parcel', $args['request_body']);
+        $this->assertArrayHasKey('Authorization', $args['headers']);
+        $this->assertIsFloat($args['request_timestamp']);
+        $this->assertEquals(13, strlen($args['request_uuid']));
+    }
+
+    /**
+     * Test that we fire a RequestHook prior to making an HTTP request.
+     */
+    public function testRequestHooks()
+    {
+        TestUtil::setupCassette('hooks/request.yml');
+
+        self::$client->subscribeToRequestHook([$this, 'requestTest']);
+        self::$client->parcel->create(Fixture::basicParcel());
+    }
+
+    /**
+     * Make assertions about a response once the ResponseHook fires.
+     */
+    public function responseTest($args)
+    {
+        $this->assertEquals(201, $args['http_status']);
+        $this->assertEquals('post', $args['method']);
+        $this->assertEquals('https://api.easypost.com/v2/parcels', $args['path']);
+        $this->assertNotNull(json_decode($args['response_body'], true)['object']);
+        $this->assertArrayHasKey('location', $args['headers']);
+        $this->assertTrue($args['response_timestamp'] > $args['request_timestamp']);
+        $this->assertEquals(13, strlen($args['request_uuid']));
+    }
+
+    /**
+     * Test that we fire a ResponseHook after receiving an HTTP response.
+     */
+    public function testResponseHooks()
+    {
+        TestUtil::setupCassette('hooks/response.yml');
+
+        self::$client->subscribeToResponseHook([$this, 'responseTest']);
+        self::$client->parcel->create(Fixture::basicParcel());
+    }
+
+    /**
+     * This function should never run since we unsubscribe from HTTP hooks.
+     */
+    public function failIfSubscribed()
+    {
+        throw new \Exception('Unsubscribing from HTTP hooks did not work as intended');
+    }
+
+    /**
+     * Test that we do not fire a hook once unsubscribed.
+     */
+    public function testUnsubscribeHooks()
+    {
+        TestUtil::setupCassette('hooks/unsubscribe.yml');
+
+        self::$client->subscribeToRequestHook([$this, 'failIfSubscribed']);
+        self::$client->unsubscribeFromRequestHook([$this, 'failIfSubscribed']);
+
+        self::$client->subscribeToResponseHook([$this, 'failIfSubscribed']);
+        self::$client->unsubscribeFromResponseHook([$this, 'failIfSubscribed']);
+
+        self::$client->parcel->create(Fixture::basicParcel());
+    }
+}