README

用于 Etsy API v3 的 PHP SDK。

此包仍在开发中。

要求

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();

nonce

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

$nonce = $client->createNonce();

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

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

验证 nonce 由您负责。如果它们不匹配，您应该丢弃响应。

有关 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问题或电子邮件讨论所提出的更改。

许可

本项目受MIT许可证许可 - 请参阅LICENSE文件以获取详细信息。

liuweikang / etsy-php-sdk

维护者

详情