README

A PHP SDK for the Etsy API v3.

此包仍在开发中。

要求

PHP 7.1 或更高版本。

安装

使用 composer 安装此包。

composer require rhysnhall/etsy-php-sdk

包含 OAuth 客户端和 Etsy 类。

use Etsy\Etsy;
use Etsy\OAuth\Client;

使用方法

授权您的应用

Etsy API 使用 OAuth 2.0 认证。您可以在他们的文档中了解更多关于 Etsy 认证的信息。

OAuth2 的第一步是请求 OAuth 令牌。您需要现有的 App API 密钥，您可以通过在这里注册应用此处获得它。

$client = new Etsy\OAuth\Client($api_key);

生成一个 URL，将用户重定向到授权访问您的应用的页面。

$url = $client->getAuthorizationUrl(
  $redirect_uri,
  $scopes,
  $code_challenge,
  $nonce
);

重定向 URI

您必须设置一个授权回调 URL。有关更多信息，请参阅 Etsy 文档。

权限范围

根据您应用的要求，您需要指定您想要授权访问的权限范围。

$scopes = ["listings_d", "listings_r", "listings_w", "profile_r"];

您可以得到所有权限范围，但通常建议只获取您需要的。

$scopes = \Etsy\Utils\PermissionScopes::ALL_SCOPES;

代码挑战

您需要生成一个 PKCE 代码挑战并保存此挑战以及用于生成挑战的验证器。您可以选择自己生成，或者让 SDK 帮您生成。

[$verifier, $code_challenge] = $client->generateChallengeCode();

一次性代码

一次性代码是一个用于 CSRF 防护的单次使用令牌。您可以使用您喜欢的任何令牌，但建议每次授权用户时让 SDK 为您生成一个。稍后用于验证响应时保存此代码。

$nonce = $client->createNonce();

此 URL 将将用户重定向到 Etsy 授权页面。如果用户授予访问权限，Etsy 将发送一个带有授权代码和一次性代码（状态）的请求。

https://www.example.com/some/location?
      code=bftcubu-wownsvftz5kowdmxnqtsuoikwqkha7_4na3igu1uy-ztu1bsken68xnw4spzum8larqbry6zsxnea4or9etuicpra5zi
      &state=superstate

您需要验证一次性代码。如果它们不匹配，您应该丢弃响应。

有关 Etsy 响应的更多信息，请参阅此处文档。

最后一步是获取用户的访问令牌。为此，您需要使用 Etsy 返回的代码发出请求。您还需要传递与第一次请求相同的回调 URL 以及用于生成 PKCE 代码挑战的验证器。

[$access_token, $refresh_token] = $client->requestAccessToken(
  $redirect_uri,
  $code,
  $verifier
);

您将获得访问令牌和刷新令牌。访问令牌的有效期为 3600 秒（1 小时）。请保存这两个令牌以供以后使用。

刷新您的令牌

您可以使用先前提供的刷新令牌来刷新您的授权令牌。这将为您提供一个新的有效访问令牌和另一个刷新令牌。

[$access_token, $refresh_token] = $client->refreshAccessToken($refresh_token);

Etsy 文档表示刷新的访问令牌的有效期为 86400 秒（24 小时），但在测试中它们似乎只在 3600 秒（1 小时）内有效。

将旧版 OAuth 1.0 令牌交换为 OAuth 2.0 令牌

如果您之前使用了 Etsy API v2 并仍然拥有用户的有效授权令牌，您可以将这些令牌更换为有效的 OAuth2 令牌。

[$access_token, $refresh_token] = $client->exchangeLegacyToken($legacy_token);

这将为您提供一套全新的 OAuth2 访问和刷新令牌。

基本使用

使用您的 App API 密钥和一个用户的访问令牌创建 Etsy 类的新实例。

$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!'
]);

集合

当有多个结果时，将返回一个集合。

$reviews = $shop->getReviews();

// Get first review.
$first = $reviews->first();

// Get 100 results using pagination.
foreach($reviews->paginate(100) as $review) {
  ...
}

完整文档将很快提供。如有任何协助需要，请发邮件至 hello@rhyshall.com。

贡献

通过贡献来帮助改进此 SDK。

在提交拉取请求之前，请先通过 Github issue 或电子邮件讨论拟议的更改。

许可

本项目采用 MIT 许可证 - 详细信息请参阅 LICENSE 文件。

teraxis / etsy-php-sdk

维护者

详情