Refactor API requests (#26)

* Add options array to request. Refactor buildOptions method.
cybercog · May 22, 2017 · 5fe8bd7 · 5fe8bd7
1 parent 958b707
commit 5fe8bd7
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 25 deletions.
diff --git 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
@@ -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
@@ -32,66 +32,71 @@ interface Client
      *
      * @param string $method
      * @param string $uri
+     * @param array $formData
      * @param array $options
      * @return \Cog\YouTrack\Rest\Response\Contracts\Response
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
@@ -80,17 +80,18 @@ 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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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,64 +113,68 @@ 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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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
      *
      * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
      * @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;
     }
 }