Add Authenticators (#19)

* Remove authentication responsibility from authorizers

* Updated Response interface naming

* Add isStatusCode assert to Response

CHANGELOG.md

@@ -2,12 +2,29 @@
 
 All notable changes to `youtrack-rest-php` will be documented in this file.
 
+## [3.0.0] - 2017-05-22
+
+### Added
+
+- `Authenticator` contract and `CookieAuthenticator` implementation.
+- `isStatusCode` assert in `Response` contract.
+
+### Updated
+
+- `CookieAuthorizer` constructor accepts `Authenticator` instead of credentials.
+- `TokenAuthorizer` constructor accepts string token instead of array.
+- `Authorizer` delegates authentication to `Authenticator`.
+- Changed namespace of `AuthenticationException`.
+- `getHeaders` method was dropped from `Authorizer` contract.
+- `Response` interface methods `getResponse`, `getStatusCode`, `getCookie`, `getLocation` were renamed to `httpResponse`, `statusCode`, `cookie`, `location` respectively.
+
 ## [2.0.1] - 2017-05-21
 
 - Dropped Client `getAuthorizer` & `setAuthorizer` rudiment methods.
 
 ## 1.0.0 - 2017-05-12
 
-- Initial release
+- Initial release.
 
+[3.0.0]: https://github.com/cybercog/youtrack-rest-php/compare/2.0.1...3.0.0
 [2.0.1]: https://github.com/cybercog/youtrack-rest-php/compare/1.0.0...2.0.1

README.md

@@ -42,6 +42,7 @@ Part of the [YouTrack PHP SDK](https://github.com/cybercog/youtrack-php-sdk#read
 - Using contracts to keep high customization capabilities.
 - Multiple authorization strategies: Token, Cookie.
 - Following PHP Standard Recommendations:
+  - [PSR-1 (Basic Coding Standard)](http://www.php-fig.org/psr/psr-1/).
   - [PSR-2 (Coding Style Guide)](http://www.php-fig.org/psr/psr-2/).
   - [PSR-4 (Autoloading Standard)](http://www.php-fig.org/psr/psr-4/).
   - [PSR-7 (HTTP Message Interface)](http://www.php-fig.org/psr/psr-7/).
@@ -98,29 +99,33 @@ require_once '/path/to/your-project/vendor/autoload.php';
 Starting with YouTrack 2017.1 release [authorization based on permanent tokens](https://www.jetbrains.com/help/youtrack/standalone/2017.2/Manage-Permanent-Token.html) is recommended as the main approach for the authorization in your REST API calls. 
 
 ```php
+// Instantiate HTTP Client
 $http = new \GuzzleHttp\Client([
     'base_uri' => 'https://example.com',
 ]);
 
-$authorizer = new \Cog\YouTrack\Rest\Authorizer\TokenAuthorizer([
-    'token' => 'YOUTRACK_API_TOKEN',
-]);
+// Instantiate YouTrack API Token Authorizer
+$authorizer = new \Cog\YouTrack\Rest\Authorizer\TokenAuthorizer('YOUTRACK_API_TOKEN');
 
+// Instantiate YouTrack API Client
 $youtrack = new \Cog\YouTrack\Rest\YouTrackClient($http, $authorizer);
 ```
 
 #### Cookie Authorizer
 
 ```php
+// Instantiate HTTP Client
 $http = new \GuzzleHttp\Client([
     'base_uri' => 'https://example.com',
 ]);
 
-$authorizer = new \Cog\YouTrack\Rest\Authorizer\CookieAuthorizer([
-    'username' => 'YOUTRACK_USERNAME',
-    'password' => 'YOUTRACK_PASSWORD',
-]);
+// Instantiate YouTrack API Cookie Authenticator
+$authenticator = new \Cog\YouTrack\Rest\Authenticator\CookieAuthenticator('YOUTRACK_USERNAME', 'YOUTRACK_PASSWORD');
+
+// Instantiate YouTrack API Cookie Authorizer
+$authorizer = new \Cog\YouTrack\Rest\Authorizer\CookieAuthorizer($authenticator);
 
+// Instantiate YouTrack API Client
 $youtrack = new \Cog\YouTrack\Rest\YouTrackClient($http, $authorizer);
 ```
 
@@ -164,25 +169,25 @@ Each successful request to the API returns instance of `\Cog\YouTrack\Rest\Respo
 
 #### Get PSR HTTP response
 
-PSR HTTP response could be accessed by calling `getResponse` method on API Response.
+PSR HTTP response could be accessed by calling `httpResponse` method on API Response.
 
 ```php
 $youtrackResponse = $youtrack->get('/issue/TEST-1');
-$psrResponse = $youtrackResponse->getResponse();
+$psrResponse = $youtrackResponse->httpResponse();
 ```
 
 #### Get response Cookie
 
 ```php
 $apiResponse = $youtrack->get('/issue/TEST-1');
-$cookieString = $apiResponse->getCookie();
+$cookieString = $apiResponse->cookie();
 ```
 
 #### Get response Location
 
 ```php
 $apiResponse = $youtrack->get('/issue/TEST-1');
-$location = $apiResponse->getLocation();
+$location = $apiResponse->location();
 ```
 
 #### Transform response to array
@@ -196,7 +201,7 @@ $location = $apiResponse->toArray();
 
 ```php
 $apiResponse = $youtrack->get('/issue/TEST-1');
-$location = $apiResponse->getStatusCode();
+$location = $apiResponse->statusCode();
 ```
 
 ## Change log

examples/cookie-authorization.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of YouTrack REST PHP.
+ *
+ * (c) Anton Komarev <a.komarev@cybercog.su>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+// Boot third party libraries
+require_once __DIR__ . '/../vendor/autoload.php';
+
+// Application configuration (replace with your YouTrack server values)
+$apiBaseUri = 'https://write-youtrack-domain.here';
+$apiUsername = 'YOUR_USERNAME';
+$apiPassword = 'YOUR_PASSWORD';
+
+// Instantiate HTTP Client
+$http = new \GuzzleHttp\Client([
+    'base_uri' => $apiBaseUri,
+]);
+
+// Instantiate YouTrack API Cookie Authenticator
+$authenticator = new \Cog\YouTrack\Rest\Authenticator\CookieAuthenticator($apiUsername, $apiPassword);
+
+// Instantiate YouTrack API Cookie Authorizer
+$authorizer = new \Cog\YouTrack\Rest\Authorizer\CookieAuthorizer($authenticator);
+
+// Instantiate YouTrack API Client
+$client = new \Cog\YouTrack\Rest\Client\YouTrackClient($http, $authorizer);
+
+// Do request to the API
+$response = $client->get('/admin/project');
+
+// Convert response to array
+$projects = $response->toArray();
+
+// Render projects one by one
+echo 'Project list:';
+foreach ($projects as $project) {
+    echo ' #' . $project['id'];
+}

examples/project-list.php → examples/token-authorization.php

@@ -23,10 +23,8 @@
     'base_uri' => $apiBaseUri,
 ]);
 
-// Instantiate YouTrack API Authorizer
-$authorizer = new \Cog\YouTrack\Rest\Authorizer\TokenAuthorizer([
-    'token' => $apiAuthToken,
-]);
+// Instantiate YouTrack API Token Authorizer
+$authorizer = new \Cog\YouTrack\Rest\Authorizer\TokenAuthorizer($apiAuthToken);
 
 // Instantiate YouTrack API Client
 $client = new \Cog\YouTrack\Rest\Client\YouTrackClient($http, $authorizer);

src/Authenticator/Contracts/Authenticator.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of YouTrack REST PHP.
+ *
+ * (c) Anton Komarev <a.komarev@cybercog.su>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\YouTrack\Rest\Authenticator\Contracts;
+
+use Cog\YouTrack\Rest\Client\Contracts\Client as ClientContract;
+
+/**
+ * Interface Authorizer.
+ *
+ * @package Cog\YouTrack\Rest\Authenticator\Contracts
+ */
+interface Authenticator
+{
+    /**
+     * Authenticate API Client.
+     *
+     * @param \Cog\YouTrack\Rest\Client\Contracts\Client $client
+     * @return void
+     */
+    public function authenticate(ClientContract $client): void;
+}

src/Authenticator/CookieAuthenticator.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of YouTrack REST PHP.
+ *
+ * (c) Anton Komarev <a.komarev@cybercog.su>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\YouTrack\Rest\Authenticator;
+
+use Cog\YouTrack\Rest\Authenticator\Contracts\Authenticator as AuthenticatorContract;
+use Cog\YouTrack\Rest\Client\Contracts\Client as ClientContract;
+
+/**
+ * Class CookieAuthenticator.
+ *
+ * @package Cog\YouTrack\Rest\Authenticator
+ */
+class CookieAuthenticator implements AuthenticatorContract
+{
+    /**
+     * @var string
+     */
+    private $username = '';
+
+    /**
+     * @var string
+     */
+    private $password = '';
+
+    /**
+     * @var string
+     */
+    private $cookie = '';
+
+    /**
+     * Determine is trying to authenticate.
+     *
+     * @var bool
+     */
+    private $isAuthenticating = false;
+
+    /**
+     * CookieAuthenticator constructor.
+     *
+     * @param string $username
+     * @param string $password
+     */
+    public function __construct(string $username, string $password)
+    {
+        $this->username = $username;
+        $this->password = $password;
+    }
+
+    /**
+     * Authenticate client and returns cookie on success login.
+     *
+     * @param \Cog\YouTrack\Rest\Client\Contracts\Client $client
+     * @return void
+     *
+     * @throws \Cog\YouTrack\Rest\Authenticator\Exceptions\AuthenticationException
+     */
+    public function authenticate(ClientContract $client): void
+    {
+        if ($this->cookie === '' && !$this->isAuthenticating) {
+            $this->isAuthenticating = true;
+            $response = $client->request('POST', '/user/login', [
+                'login' => $this->username,
+                'password' => $this->password,
+            ]);
+            $this->isAuthenticating = false;
+
+            if ($response->isStatusCode(200)) {
+                $this->cookie = $response->cookie();
+            }
+        }
+
+        $client->putHeader('Cookie', $this->cookie);
+    }
+}

src/Authorizer/Exceptions/AuthenticationException.php → src/Authenticator/Exceptions/AuthenticationException.php

@@ -11,12 +11,14 @@
  * file that was distributed with this source code.
  */
 
-namespace Cog\YouTrack\Rest\Authorizer\Exceptions;
+namespace Cog\YouTrack\Rest\Authenticator\Exceptions;
+
+use Cog\YouTrack\Rest\Authorizer\Exceptions\AuthorizationException;
 
 /**
  * Class AuthenticationException.
  *
- * @package Cog\YouTrack\Rest\Authorizer\Exceptions
+ * @package Cog\YouTrack\Rest\Authenticator\Exceptions
  */
 class AuthenticationException extends AuthorizationException
 {

src/Authorizer/Contracts/Authorizer.php

@@ -25,15 +25,8 @@ interface Authorizer
     /**
      * Returns authorization headers.
      *
-     * @return array
-     */
-    public function getHeaders(): array;
-
-    /**
-     * Authenticate API Client.
-     *
      * @param \Cog\YouTrack\Rest\Client\Contracts\Client $client
      * @return void
      */
-    public function authenticate(ClientContract $client): void;
+    public function appendHeadersTo(ClientContract $client): void;
 }