README

Etsy API v3 的 PHP SDK。

2024年7月13日进行了主要更新。这次更新修复了所有主要问题，并增加了对API最近添加资源的支持。如果您是从此版本之前的版本升级的，请考虑这是一次重大更改。没有升级路径，您需要审查所有代码。

正式文档还在制作中。想帮我写吗？我会请你喝冰拿铁。

要求

PHP 8 或更高版本。

安装

使用 composer 安装此包。

composer require rhysnhall/etsy-php-sdk

包含 Etsy 类。

use Etsy\Etsy;

$etsy = new Etsy(
  $client_id,
  $access_token
);

// Do the Etsy things.

用法

授权您的应用程序

Etsy API 使用 OAuth 2.0 身份验证。您可以在他们的 文档 中了解有关使用 Etsy 进行身份验证的更多信息。

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

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

生成一个 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 资源。

use Etsy\Etsy;
use Etsy\Resources\User;

$etsy = new Etsy($apiKey, $accessToken);

// Get the authenticated user.
$user = User::me();

// Get the users shop.
$shop = $user->shop();

资源

大多数调用将返回一个 Resource。资源包含许多方法，可简化您与 Etsy API 的交互。

// Get a Listing Resource
$listing = \Etsy\Resources\Listing::get($shopId);

资源包含 Etsy 的 API 响应作为属性。

$listingTitle = $listing->title;

关联

资源将返回关联，作为它们各自的资源。例如，以下调用将返回 shop 属性作为 Etsy\Resources\Shop 的实例。

$shop = $listing->shop;

toJson

toJson 方法将返回资源作为 JSON 编码的对象。

$json = $listing->toJson();

toArray

toArray 方法将返回资源作为数组。

$array = $listing->toArray();

集合

当结果超过一个时，将返回集合。

$reviews = Review::all();

结果存储在集合的 data 属性中，作为 Resource 数组。

$firstReview = $reviews->data[0];

集合包含一些有用的方法。

first

获取集合中的第一个项目。

$firstReview = $reviews->first();

count

获取集合中的结果数量。不要与显示整个 Etsy 资源中结果数量的 count 属性混淆。

$count = $reviews->count();

append

将属性附加到集合中的每个项目。

$reviews->append(['shop_id' => $shopId]);

paginate

大多数 Etsy 方法每调用最多返回 100 个结果。您可以使用 paginate 方法获取比这更多的结果（最多 500 个结果）。

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

toJson

返回集合中的项目作为 JSON 字符串数组。

$jsonArray = $reviews->toJson();

直接请求

您可以使用 Etsy 类的静态 $client 属性直接向 Etsy API 发送请求。

$response = Etsy::$client->get(
  "/application/listings/active",
  [
    "limit" => 25
  ]
);

如果您仍然想使用资源类，可以将响应转换为资源。

$listings = Etsy::getResource(
  $response,
  'Listing'
);

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

贡献

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

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

许可

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