Merge pull request #31 from ethancarlsson-pf/ethan.carlsson/DEV-4690

Ethan.carlsson/dev 4690 - Update authorization with OAuth in SDK

Author: ethancarlsson-pf

README.md

@@ -12,3 +12,29 @@ API endpoint documentation can be found here: https://www.printful.com/docs
 Using composer, run `composer require printful/php-api-sdk`
 
 Check out **example** and **test** directories for more specific usage examples.
+
+# OAuth
+[OAuth 2.0](https://developers.printful.com/docs/#section/Authentication:~:text=OAuth%202.0%20is%20the%20preferred%20way%20of%20doing%20authorization%20in%20Printful%20API.)
+is the preferred way of doing authorization in Printful API. Read more about how to acquire and
+use an access token in our docs: https://developers.printful.com/docs/#section/Authentication
+
+You can create an OAuth enabled APIClient using the following factory method:
+```php
+...
+use Printful\PrintfulApiClient;
+... 
+$client = PrintfulApiClient::createOauthClient('my-oauth-token')
+```
+
+You can still use the old store keys, like this:
+```php
+...
+use Printful\PrintfulApiClient;
+... 
+$client = PrintfulApiClient::createLegacyStoreKeyClient('my-legacy-store-key')
+```
+or, by using the constructor like this:
+```php
+$client = new PrintfulApiClient($storeKey)
+```
+However, please note that legacy keys will be phased out on September 30th, 2022.

src/PrintfulApiClient.php

@@ -10,11 +10,21 @@
  */
 class PrintfulApiClient
 {
+    const TYPE_LEGACY_STORE_KEY = 'legacy-store-key';
+    const TYPE_OAUTH_TOKEN = 'oauth-token';
+    const DEFAULT_KEY = self::TYPE_LEGACY_STORE_KEY;
+
     /**
      * Printful API key
-     * @var string
+     * @var string|null
+     */
+    private $legacyStoreKey;
+
+    /**
+     * Printful OAuth token
+     * @var string|null
      */
-    private $key = '';
+    private $oauthToken;
 
     private $lastResponseRaw;
 
@@ -37,16 +47,36 @@ class PrintfulApiClient
     public $curlTimeout = 20;
 
     /**
-     * @param string $key Printful Store API key
+     * @param string $key
+     * @param string $type // PrintfulApiClient::TYPE_LEGACY_STORE_KEY or PrintfulApiClient::TYPE_OAUTH_TOKEN
      * @throws \Printful\Exceptions\PrintfulException if the library failed to initialize
      */
-    public function __construct($key)
+    public function __construct($key, $type = self::DEFAULT_KEY)
     {
-        if (strlen($key) < 32) {
-            throw new PrintfulException('Missing or invalid Printful store key!');
+        if ($type === self::TYPE_LEGACY_STORE_KEY && strlen($key) < 32) {
+            throw new PrintfulException('Invalid Printful store key!');
         }
 
-        $this->key = $key;
+        $this->legacyStoreKey = $type === self::TYPE_LEGACY_STORE_KEY ? $key : null;
+        $this->oauthToken = $type === self::TYPE_OAUTH_TOKEN ? $key : null;
+    }
+
+    /**
+     * @param string $oAuthToken
+     * @throws PrintfulException
+     */
+    public static function createOauthClient($oAuthToken)
+    {
+        return new self($oAuthToken, self::TYPE_OAUTH_TOKEN);
+    }
+
+    /**
+     * @param string $legacyStoreKey
+     * @throws PrintfulException
+     */
+    public static function createLegacyStoreKeyClient($legacyStoreKey)
+    {
+        return new self($legacyStoreKey, self::TYPE_LEGACY_STORE_KEY);
     }
 
     /**
@@ -154,7 +184,8 @@ private function request($method, $path, array $params = [], $data = null)
 
         $curl = curl_init($this->url . $url);
 
-        curl_setopt($curl, CURLOPT_USERPWD, $this->key);
+        $this->setCredentials($curl);
+
         curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method);
         curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
         curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
@@ -194,4 +225,19 @@ private function request($method, $path, array $params = [], $data = null)
         }
         return $response['result'];
     }
+
+    /**
+     * @param resource $curl
+     * @throws PrintfulException
+     */
+    private function setCredentials($curl)
+    {
+        if ($this->oauthToken !== null) {
+            curl_setopt($curl, CURLOPT_HTTPHEADER, ["Authorization: Bearer $this->oauthToken"]);
+        } elseif ($this->legacyStoreKey !== null) {
+            curl_setopt($curl, CURLOPT_USERPWD, $this->legacyStoreKey);
+        } else {
+            throw new PrintfulException('Either OAuth token or store key must be set to make this request.');
+        }
+    }
 }

tests/ApiClient/PrintfulApiClientTest.php

@@ -0,0 +1,81 @@
+<?php
+
+namespace Printful\Tests\ApiClient;
+
+use Printful\Exceptions\PrintfulException;
+use Printful\PrintfulApiClient;
+use Printful\Tests\Credentials;
+use Printful\Tests\TestCase;
+
+class PrintfulApiClientTest extends TestCase
+{
+    /**
+     * @throws \Printful\Exceptions\PrintfulException
+     * @throws \Printful\Exceptions\PrintfulApiException
+     */
+    public function testGet_withApiKey_returnsWithNoAuthErrors()
+    {
+        if (Credentials::$legacyStoreKey === '') {
+            $this->markTestSkipped('You need apiKey to be set in Credentials.php for this test to run');
+        }
+
+        $sut = PrintfulApiClient::createLegacyStoreKeyClient(Credentials::$legacyStoreKey);
+
+        $this->overrideUrl($sut);
+
+        $result = $sut->get('orders', [
+            'offset' => 0,
+            'limit' => 10,
+            'status' => null,
+        ]);
+
+        self::assertNotNull($result);
+    }
+
+    /**
+     * @throws \Printful\Exceptions\PrintfulException
+     * @throws \Printful\Exceptions\PrintfulApiException
+     */
+    public function testGet_withOauthToken_returnsWithNoAuthErrors()
+    {
+        if (Credentials::$oAuthToken === '') {
+            $this->markTestSkipped('You need oAuthToken to be set in Credentials.php for this test to run');
+        }
+
+        $sut = PrintfulApiClient::createOauthClient(Credentials::$oAuthToken);
+
+        $this->overrideUrl($sut);
+
+        $result = $sut->get('orders', [
+            'offset' => 0,
+            'limit' => 10,
+            'status' => null,
+        ]);
+        self::assertNotNull($result);
+    }
+
+    /**
+     * @throws \Printful\Exceptions\PrintfulException
+     * @throws \Printful\Exceptions\PrintfulApiException
+     */
+    public function testGet_withInvalidCredentials_throwsApiException()
+    {
+        $sut = PrintfulApiClient::createOauthClient('invalid key');
+
+        $this->overrideUrl($sut);
+
+        $this->expectException(PrintfulException::class);
+        $sut->get('orders', [
+            'offset' => 0,
+            'limit' => 10,
+            'status' => null,
+        ]);
+    }
+
+    private function overrideUrl(PrintfulApiClient $sut)
+    {
+        if (Credentials::$apiUrlOverride) {
+            $sut->url = Credentials::$apiUrlOverride;
+        }
+    }
+}

tests/Credentials.php.dist

@@ -11,7 +11,12 @@ class Credentials
     /**
      * @var string
      */
-    public static $apiKey = '';
+    public static $legacyStoreKey = '';
+
+    /**
+     * @var string
+     */
+    public static $oAuthToken = '';
 
     /**
      * Option to override API URL

tests/TestCase.php

@@ -10,6 +10,10 @@ abstract class TestCase extends \PHPUnit_Framework_TestCase
     /** @var PrintfulApiClient */
     protected $api;
 
+    /**
+     * @throws \Printful\Exceptions\PrintfulException
+     * @throws \Exception
+     */
     protected function setUp()
     {
         parent::setUp();
@@ -18,7 +22,13 @@ protected function setUp()
             throw new \Exception('Printful test credentials are not set. Copy "tests/Credentials.php.dist" to "tests/Credentials.php and enter the API key');
         }
 
-        $this->api = new PrintfulApiClient(Credentials::$apiKey);
+        if (Credentials::$oAuthToken !== '') {
+            $this->api = PrintfulApiClient::createOauthClient(Credentials::$oAuthToken);
+        } elseif (Credentials::$legacyStoreKey !== '') {
+            $this->api = PrintfulApiClient::createLegacyStoreKeyClient(Credentials::$legacyStoreKey);
+        } else {
+            throw new \Exception('Printful test credentials are not set. Please enter a valid $oAuthToken or $legacyStoreKey in your tests/Credentials.php file');
+        }
 
         // Override API URL if is set
         if (Credentials::$apiUrlOverride) {