Updated with support for Etsy API v3.

Removed all supported for Etsy API v2.
rhysnhall · Aug 5, 2021 · 9eeccb2 · 9eeccb2
1 parent 88f2629
commit 9eeccb2
Show file tree

Hide file tree

Showing 45 changed files with 1,046 additions and 1,786 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,7 @@
+# Changelog
+
+## v0.1
+First actual version.
+
+* Added support for the Etsy API v3.
+* Removed support for Etsy API v2
diff --git a/README.md b/README.md
@@ -1,74 +1,151 @@
 # Etsy PHP SDK
-An unofficial PHP SDK for the Etsy API.
+An unofficial PHP SDK for the Etsy API v3.
 
-This package is still in development. It is not stable to directly use.
+This package is still in development. **Listing Management** resources are currently not available.
 
 ## Requirements
-PHP 5.6.0 or greater.
+PHP 7.0 or greater.
+
+## Install
+Install the package using composer.
+```php
+composer require rhysnhall/etsy-php-sdk
+```
+
+Include the OAuth client and Etsy class.
+```php
+use Etsy\Etsy;
+use Etsy\OAuth\Client;
+```
 
 ## Usage
 
 ### Authorizing your app
-The Etsy API uses OAuth 1.0 authentication. You can read more about authenticating with Etsy on their [documentation](https://www.etsy.com/developers/documentation/getting_started/oauth).
+The Etsy API uses OAuth 2.0 authentication. You can read more about authenticating with Etsy on their [documentation](https://developers.etsy.com/documentation/essentials/authentication).
 
-The first step in OAuth is to obtain temporary credentials. You will need an existing API consumer key and secret which you can obtain by registering an app [here](https://www.etsy.com/developers/register).
+The first step in OAuth2 is to request an OAuth token. You will need an existing App API key which you can obtained by registering an app [here](https://www.etsy.com/developers/register).
 ```php
-Etsy::setConfig([
-  'consumer_key' => $consumer_key,
-  'consumer_secret' => $consumer_secret
-]);
-$etsy = new Etsy;
+$client = new Etsy\OAuth\Client($api_key);
 ```
 
-Obtain the temporary credentials and save them.
+Generate a URL to redirect the user to authorize access to your app.
 ```php
-$temp_credentials = $etsy->getTemporaryCredentials();
+$url = $client->getAuthorizationUrl(
+  $redirect_uri,
+  $scopes,
+  $code_challenge,
+  $nonce
+);
 ```
 
-Generate a URL to redirect the user to authorize access to your app.
+###### Redirect URI
+You must set an authorized callback URL. Check out the [Etsy documentation](https://developers.etsy.com/documentation/essentials/authentication#redirect-uris) for further information.
+
+###### Scope
+Depending on your apps requirements, you will need to specify the [permission scopes](https://developers.etsy.com/documentation/essentials/authentication#scopes) you want to authorize access for.
 ```php
-$redirect_url = $etsy->getAuthorizationUrl();
+$scopes = ["listings_d", "listings_r", "listings_w", "profile_r"];
 ```
 
-Depending on your apps requirements, you will need to specify the [permission scopes](https://www.etsy.com/developers/documentation/getting_started/oauth#section_permission_scopes) you want to authorize access for. This should be done when setting the config. You can use either an array or a string to define the scope.
+You can get all scopes, but it is generally recommended to only get what you need.
+```php
+$scopes = \Etsy\Utils\PermissionScopes::ALL_SCOPES;
+```
 
-Additionally, you will most likely want to set a callback URL.
+###### Code challenge
+You'll need to generate a [PKCE code challenge](https://developers.etsy.com/documentation/essentials/authentication#proof-key-for-code-exchange-pkce) and save this along with the verifier used to generate the challenge. You are welcome to generate your own, or let the SDK do this for you.
 ```php
-Etsy::setConfig([
-  'consumer_key' => $consumer_key,
-  'consumer_secret' => $consumer_secret,
-  'scope' => ['listings_r', 'transactions_r'],
-  'callback_uri' => 'my-etsy-app/authorize'
-]);
+[$verifier, $code_challenge] = $client->generateChallengeCode();
 ```
 
-You can get all scopes, but it is generally recommended to only get what you need.
+###### Nonce
+The nonce is a single use token used for CSRF protection. You can use any token you like but it is recommended to let the SDK generate one for you each time you authorize a user. Save this for verifying the response later on.
 ```php
-\Etsy\Utils\PermissionScopes::ALL_SCOPES
+$nonce = $client->createNonce();
 ```
 
-Upon successful authorization, the user will be redirected to your URL along with two query string parameters called **oauth_verifier** and **oauth_token**.
 
-You now only have a small window of time to complete the last step before the verifier expires.
+The URL will redirect your user to the Etsy authorization page. If the user grants access, Etsy will send back a request with an authorization code and the nonce (state).
+```curl
+https://www.example.com/some/location?
+      code=bftcubu-wownsvftz5kowdmxnqtsuoikwqkha7_4na3igu1uy-ztu1bsken68xnw4spzum8larqbry6zsxnea4or9etuicpra5zi
+      &state=superstate
+```
+
+It is up to you to validate the nonce. If they do not match you should discard the response.
 
-To complete authorization, you will need to request OAuth token credentials.
+For more information on Etsy's response, check out the [documentation here](https://developers.etsy.com/documentation/essentials/authentication#step-2-grant-access).
+
+The final step is to get the access token for the user. To do this you will need to make a request using the code that was just returned by Etsy. You will also need to pass in the same callback URL as the first request and the verifier used to generate the PKCE code challenge.
 ```php
-$token_credentials = $etsy->getTokenCredentials($temp_creds, $oauth_token, $oauth_verifier);
+[$access_token, $refresh_token] = $client->requestAccessToken(
+  $redirect_uri,
+  $code,
+  $verifier
+);
 ```
 
-Save these credentials as they will remain valid until the they are revoked, and can be reused for the specific user moving forward.
+You'll be provided with both an access token and a refresh token. The access token has a valid duration of 3600 seconds (1 hour). Save both of these for late ruse.
+
+#### Refreshing your token
+
+You can refresh your authorization token using the refresh token that was previously provided. This will provide you with a new valid access token and another refresh token.
 
-The next time you set the Etsy config, include these access credentials to skip the need to repeat the above process.
-The config will also accept optional keys **user_id** and **shop_id**.
 ```php
-Etsy::setConfig([
-  'consumer_key' => $consumer_key,
-  'consumer_secret' => $consumer_secret,
-  'access_key' => $access_key,
-  'access_secret' => $access_secret,
-
-  // Optional
-  'user_id' => $user_id,
-  'shop_id' => $shop_id
+[$access_token, $refresh_token] = $client->refreshAccessToken($refresh_token);
+```
+
+The [Etsy documentation](https://developers.etsy.com/documentation/essentials/authentication#requesting-a-refresh-oauth-token) states that refreshed access tokens have a duration of 86400 seconds (24 hours) but on testing they appear to only remain valid for up 3600 seconds (1 hour).
+
+#### Exchanging legacy OAuth 1.0 token for OAuth 2.0 token
+If you previously used v2 of the Etsy API and still have valid authorization tokens for your users, you may swap these over for valid OAuth2 tokens.
+```php
+[$access_token, $refresh_token] = $client->exchangeLegacyToken($legacy_token);
+```
+
+This will provide you with a brand new set of OAuth2 access and refresh tokens.
+
+### Basic use
+
+Create a new instance of the Etsy class using your App API key and a user's access token.
+
+```php
+$etsy = new Etsy\Etsy($api_key, $access_token);
+
+// Get user.
+$user = $etsy->getUser();
+
+// Get shop.
+$shop = $user->getShop();
+
+// Update shop.
+$shop->update([
+  'title' => 'My exciting shop!'
 ]);
 ```
+
+###### Collections
+When there is more than one result a collection will be returned.
+```php
+$reviews = $shop->getReviews();
+
+// Get first review.
+$first = $reviews->first();
+
+// Get 100 results using pagination.
+foreach($reviews->paginate(100) as $review) {
+  ...
+}
+```
+
+---
+
+Full documentation will be available soon. Email [hello@rhyshall.com](mailto:hello@rhyshall.com) for any assistance.
+
+## Contributing
+Help improve this SDK by contributing.
+
+Before opening a pull request, please first discuss the proposed changes via Github issue or <a href="mailto:hello@rhyshall.com">email</a>.
+
+## License
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/OrbitCSS/orbitcss/blob/master/LICENSE) file for details
diff --git a/composer.json b/composer.json
@@ -1,5 +1,6 @@
 {
   "name": "rhysnhall/etsy-php-sdk",
+  "version": "0.1",
   "description": "Unofficial PHP SDK for Etsy.",
   "type": "library",
   "keywords": [
@@ -17,8 +18,8 @@
     }
   ],
   "require": {
-    "php": ">=5.6.0",
-    "y0lk/oauth1-etsy": "^1.0.2"
+    "php": ">=7.0",
+    "guzzlehttp/guzzle": "^7.3"
   },
   "autoload": {
     "psr-4": {

diff --git a/src/Collection.php b/src/Collection.php
@@ -4,6 +4,7 @@
 
 use Etsy\Etsy;
 use Etsy\Utils\Request as RequestUtil;
+use Etsy\Exception\SdkException;
 
 /**
  * Holds a collection of resources.
@@ -12,6 +13,10 @@
  */
 class Collection {
 
+  const PAGINATION_SUPPORT = [
+    "Shop", "Review"
+  ];
+
   /**
    * @var string
    */
@@ -20,18 +25,13 @@ class Collection {
   /**
    * @var string
    */
-  protected $url;
+  protected $uri = false;
 
   /**
    * @var array
    */
   protected $params = [];
 
-  /**
-   * @var integer|false
-   */
-  public $next_page = null;
-
   /**
    * @var array
    */
@@ -46,15 +46,17 @@ class Collection {
    * Constructor method for the collection.
    *
    * @param string $resource
-   * @param string $url
+   * @param string $uri
    * @return void
    */
-  public function __construct($resource, $url) {
+  public function __construct($resource, $uri = false) {
     $this->resource = $resource;
-    $url = explode('?', $url);
-    $this->url = $url[0];
-    if(isset($url[1])) {
-      $this->params = RequestUtil::getParamaters($url[1]);
+    if($uri) {
+      $uri = explode('?', $uri);
+      $this->uri = $uri[0];
+      if(isset($uri[1])) {
+        $this->params = RequestUtil::getParamaters($uri[1]);
+      }
     }
   }
 
@@ -70,6 +72,15 @@ public function first() {
     return $this->data[0];
   }
 
+  /**
+   * Returns the number of resources within the collection.
+   *
+   * @return integer
+   */
+  public function count() {
+    return count($this->data);
+  }
+
   /**
    * Appends properties to each resource in the collection.
    *
@@ -90,18 +101,31 @@ public function append($data) {
   /**
    * Paginate generator provides continued iteration against the Etsy limitations on number of records returned per call.
    *
+   * @param integer $results
    * @return void
    */
-  public function paginate() {
+  public function paginate($results = 100) {
+    // Limit max results to 500.
+    if($results > 500) {
+      $results = 500;
+    }
+    if(!in_array($this->resource, self::PAGINATION_SUPPORT)) {
+      throw new SdkException("The {$this->resource} resource does not support pagination.");
+    }
     $page = $this;
+    $count = 0;
     while(true) {
       foreach($page->data as $resource) {
         yield $resource;
       }
-      if(is_null($page->next_page)) {
+      $count += count($page->data);
+      if(!($page->next_page ?? true)
+        || $count >= $results) {
+        break;
+      }
+      if(!$page = $page->nextPage()) {
         break;
       }
-      $page = $page->nextPage();
     }
   }
 
@@ -111,16 +135,23 @@ public function paginate() {
    * @return Collection
    */
   private function nextPage() {
-    $this->params['page'] = $this->next_page;
-    $response = Etsy::makeRequest(
-      'GET',
-      $this->url,
+    $limit = $this->params['limit'] ?? 25;
+    $this->params['offset'] = ($this->params['offset'] ?? 0) + $limit;
+    $response = Etsy::$client->get(
+      $this->uri,
       $this->params
     );
-    $collection = Etsy::getCollection($response, $this->resource);
+    $collection = Etsy::getResource($response, $this->resource);
+    if(!$collection) {
+      $collection->next_page = false;
+      return false;
+    }
     if(count($this->_append)) {
       $collection->append($this->_append);
     }
+    if(count($collection->data) < $limit) {
+      $collection->next_page = false;
+    }
     return $collection;
   }