Merge pull request #78 from ConvertKit/v4-api-get-response-interface

v4 API: Expose `Response` interface

Author: n7studios

README.md

@@ -114,6 +114,26 @@ $api = new \ConvertKit_API\ConvertKit_API(
 );
 ```
 
+API requests may then be performed:
+
+```php
+$result = $api->add_subscriber_to_form(12345, '[email protected]');
+```
+
+To determine whether a new entity / relationship was created, or an existing entity / relationship updated, inspect the HTTP code of the last request:
+
+```php
+$result = $api->add_subscriber_to_form(12345, '[email protected]');
+$code = $api->getResponseInterface()->getStatusCode(); // 200 OK if e.g. a subscriber already added to the specified form, 201 Created if the subscriber added to the specified form for the first time.
+```
+
+The PSR-7 response can be fetched and further inspected, if required - for example, to check if a header exists:
+
+```php
+$result = $api->add_subscriber_to_form(12345, '[email protected]');
+$api->getResponseInterface()->hasHeader('Content-Length'); // Check if the last API request included a `Content-Length` header
+```
+
 ### 1.x (v3 API, API Key and Secret, PHP 7.4+)
 
 Get your ConvertKit API Key and API Secret [here](https://app.convertkit.com/account/edit) and set it somewhere in your application.

src/ConvertKit_API.php

@@ -95,6 +95,13 @@ class ConvertKit_API
      */
     protected $client;
 
+    /**
+     * Guzzle Http Response
+     *
+     * @var \Psr\Http\Message\ResponseInterface
+     */
+    protected $response;
+
 
     /**
      * Constructor for ConvertKitAPI instance
@@ -1750,21 +1757,32 @@ public function make_request(string $endpoint, string $method, array $args = [])
         }
 
         // Send request.
-        $response = $this->client->send(
+        $this->response = $this->client->send(
             $request,
             ['exceptions' => false]
         );
 
-        // Inspect response.
-        $status_code   = $response->getStatusCode();
-        $response_body = $response->getBody()->getContents();
+        // Get response.
+        $response_body = $this->response->getBody()->getContents();
 
         // Log response.
-        $this->create_log(sprintf('Response Status Code: %s', $response->getStatusCode()));
-        $this->create_log(sprintf('Response Body: %s', $response->getBody()->getContents()));
+        $this->create_log(sprintf('Response Status Code: %s', $this->response->getStatusCode()));
+        $this->create_log(sprintf('Response Body: %s', $response_body));
         $this->create_log('Finish request successfully');
 
         // Return response.
         return json_decode($response_body);
     }
+
+    /**
+     * Returns the response interface used for the last API request.
+     *
+     * @since 2.0.0
+     *
+     * @return \Psr\Http\Message\ResponseInterface
+     */
+    public function getResponseInterface()
+    {
+        return $this->response;
+    }
 }

tests/ConvertKitAPITest.php

@@ -61,6 +61,29 @@ protected function setUp(): void
         );
     }
 
+    /**
+     * Test that a Response instance is returned when calling getResponseInterface()
+     * after making an API request.
+     *
+     * @since   2.0.0
+     *
+     * @return  void
+     */
+    public function testGetResponseInterface()
+    {
+        // Assert response interface is null, as no API request made.
+        $this->assertNull($this->api->getResponseInterface());
+
+        // Perform an API request.
+        $result = $this->api->get_account();
+
+        // Assert response interface is of a valid type.
+        $this->assertInstanceOf(Response::class, $this->api->getResponseInterface());
+
+        // Assert the correct status code was returned.
+        $this->assertEquals(200, $this->api->getResponseInterface()->getStatusCode());
+    }
+
     /**
      * Test that a ClientInterface can be injected.
      *
@@ -95,6 +118,12 @@ public function testClientInterfaceInjection()
         $this->assertSame('Test Account for Guzzle Mock', $result->name);
         $this->assertSame('free', $result->plan_type);
         $this->assertSame('[email protected]', $result->primary_email_address);
+
+        // Assert response interface is of a valid type when using `set_http_client`.
+        $this->assertInstanceOf(Response::class, $this->api->getResponseInterface());
+
+        // Assert the correct status code was returned.
+        $this->assertEquals(200, $this->api->getResponseInterface()->getStatusCode());
     }
 
     /**