From 5fe8bd7a883163a8c5e84b48973aeb7d9980908c Mon Sep 17 00:00:00 2001
From: Pe Ell <a-komarev@users.noreply.github.com>
Date: Mon, 22 May 2017 11:13:32 +0300
Subject: [PATCH] Refactor API requests (#26)

* Add options array to request. Refactor buildOptions method.
---
 CHANGELOG.md                    |  1 +
 README.md                       | 22 +++++++++++++--
 src/Client/Contracts/Client.php | 15 +++++++----
 src/Client/YouTrackClient.php   | 47 ++++++++++++++++++++-------------
 4 files changed, 60 insertions(+), 25 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3e48ef8..458b5c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,6 +21,7 @@ All notable changes to `youtrack-rest-php` will be documented in this file.
 - `Response` interface methods `getResponse`, `getStatusCode`, `getCookie`, `getLocation` were renamed to `httpResponse`, `statusCode`, `cookie`, `location` respectively.
 - `User-Agent` header is more verbose.
 - REST Client version is defined in `Client` contract instead of each concrete implementation.
+- Additional param `$options` was added to `Client` methods: `request`, `get`, `post`, `put`, `delete`.
 
 ## [2.0.1] - 2017-05-21
 
diff --git a/README.md b/README.md
index 70a79b7..1d86f2c 100644
--- a/README.md
+++ b/README.md
@@ -140,8 +140,26 @@ $youtrack = new \Cog\YouTrack\Rest\YouTrackClient($httpClient, $authorizer);
 #### HTTP request
 
 ```php
-$method = 'GET'; // POST, PUT, DELETE, PATCH or any custom ones
-$response = $youtrack->request($method, '/issue/TEST-1');
+$method = 'POST'; // GET, POST, PUT, DELETE, PATCH or any custom ones
+$response = $youtrack->request($method, '/issue', [
+    'project' => 'TEST',
+    'summary' => 'New test issue',
+    'description' => 'Test description',
+]);
+```
+
+You can [customize requests created and transferred by a client using request options](http://docs.guzzlephp.org/en/latest/request-options.html). Request options control various aspects of a request including, headers, query string parameters, timeout settings, the body of a request, and much more.
+
+```php
+$options = [
+    'debug' => true,
+    'sink' => '/path/to/dump/file',
+];
+$response = $youtrack->request('POST', '/issue', [
+    'project' => 'TEST',
+    'summary' => 'New test issue',
+    'description' => 'Test description',
+], $options);
 ```
 
 #### HTTP GET request
diff --git a/src/Client/Contracts/Client.php b/src/Client/Contracts/Client.php
index 365dcb0..50e693e 100644
--- a/src/Client/Contracts/Client.php
+++ b/src/Client/Contracts/Client.php
@@ -32,6 +32,7 @@ interface Client
      *
      * @param string $method
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -39,12 +40,13 @@ interface Client
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function request(string $method, string $uri, array $options = []) : ResponseContract;
+    public function request(string $method, string $uri, array $formData = [], array $options = []): ResponseContract;
 
     /**
      * Create and send an GET HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -52,12 +54,13 @@ public function request(string $method, string $uri, array $options = []) : Resp
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function get(string $uri, array $options = []): ResponseContract;
+    public function get(string $uri, array $formData = [], array $options = []): ResponseContract;
 
     /**
      * Create and send an POST HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -65,12 +68,13 @@ public function get(string $uri, array $options = []): ResponseContract;
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function post(string $uri, array $options = []): ResponseContract;
+    public function post(string $uri, array $formData = [], array $options = []): ResponseContract;
 
     /**
      * Create and send an PUT HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -78,12 +82,13 @@ public function post(string $uri, array $options = []): ResponseContract;
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function put(string $uri, array $options = []): ResponseContract;
+    public function put(string $uri, array $formData = [], array $options = []): ResponseContract;
 
     /**
      * Create and send an DELETE HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -91,7 +96,7 @@ public function put(string $uri, array $options = []): ResponseContract;
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function delete(string $uri, array $options = []): ResponseContract;
+    public function delete(string $uri, array $formData = [], array $options = []): ResponseContract;
 
     /**
      * Write header value.
diff --git a/src/Client/YouTrackClient.php b/src/Client/YouTrackClient.php
index 2fc978a..2ab673a 100644
--- a/src/Client/YouTrackClient.php
+++ b/src/Client/YouTrackClient.php
@@ -80,6 +80,7 @@ public function __construct(HttpClientContract $httpClient, AuthorizerContract $
      *
      * @param string $method
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -87,10 +88,10 @@ public function __construct(HttpClientContract $httpClient, AuthorizerContract $
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function request(string $method, string $uri, array $options = []) : ResponseContract
+    public function request(string $method, string $uri, array $formData = [], array $options = []) : ResponseContract
     {
         try {
-            $response = $this->httpClient->request($method, $this->buildUri($uri), $this->buildOptions($options));
+            $response = $this->httpClient->request($method, $this->buildUri($uri), $this->buildOptions($formData, $options));
         } catch (HttpClientException $e) {
             switch ($e->getCode()) {
                 case 401:
@@ -112,6 +113,7 @@ public function request(string $method, string $uri, array $options = []) : Resp
      * Create and send an GET HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -119,15 +121,16 @@ public function request(string $method, string $uri, array $options = []) : Resp
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function get(string $uri, array $options = []): ResponseContract
+    public function get(string $uri, array $formData = [], array $options = []): ResponseContract
     {
-        return $this->request('GET', $uri, $options);
+        return $this->request('GET', $uri, $formData, $options);
     }
 
     /**
      * Create and send an POST HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -135,15 +138,16 @@ public function get(string $uri, array $options = []): ResponseContract
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function post(string $uri, array $options = []): ResponseContract
+    public function post(string $uri, array $formData = [], array $options = []): ResponseContract
     {
-        return $this->request('POST', $uri, $options);
+        return $this->request('POST', $uri, $formData, $options);
     }
 
     /**
      * Create and send an PUT HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -151,15 +155,16 @@ public function post(string $uri, array $options = []): ResponseContract
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function put(string $uri, array $options = []): ResponseContract
+    public function put(string $uri, array $formData = [], array $options = []): ResponseContract
     {
-        return $this->request('PUT', $uri, $options);
+        return $this->request('PUT', $uri, $formData, $options);
     }
 
     /**
      * Create and send an DELETE HTTP request.
      *
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
@@ -167,9 +172,9 @@ public function put(string $uri, array $options = []): ResponseContract
      * @throws \Cog\YouTrack\Rest\Authorizer\Exceptions\InvalidTokenException
      * @throws \Cog\YouTrack\Rest\Client\Exceptions\ClientException
      */
-    public function delete(string $uri, array $options = []): ResponseContract
+    public function delete(string $uri, array $formData = [], array $options = []): ResponseContract
     {
-        return $this->request('DELETE', $uri, $options);
+        return $this->request('DELETE', $uri, $formData, $options);
     }
 
     /**
@@ -198,23 +203,33 @@ protected function buildUri(string $uri): string
      * Build request options.
      *
      * @param array $formData
+     * @param array $options
      * @return array
      */
-    protected function buildOptions(array $formData = []): array
+    protected function buildOptions(array $formData = [], $options = []): array
     {
-        return [
+        $defaultOptions = [
             'form_params' => $formData,
             'headers' => $this->buildHeaders(),
         ];
+
+        if (isset($options['form_params'])) {
+            $options['form_params'] = array_merge($formData, $options['form_params']);
+        }
+
+        if (isset($options['headers'])) {
+            $options['headers'] = array_merge($this->buildHeaders(), $options['headers']);
+        }
+
+        return array_merge($defaultOptions, $options);
     }
 
     /**
      * Build request headers.
      *
-     * @param array $options
      * @return array
      */
-    protected function buildHeaders(array $options = []): array
+    protected function buildHeaders(): array
     {
         $this->headers = [
             'User-Agent' => 'Cog-YouTrack-REST-PHP/' . self::VERSION,
@@ -223,10 +238,6 @@ protected function buildHeaders(array $options = []): array
 
         $this->authorizer->appendHeadersTo($this);
 
-        if (isset($options['headers'])) {
-            $this->headers = array_merge($this->headers, $options['headers']);
-        }
-
         return $this->headers;
     }
 }