README

PHP的Envato API客户端，支持简化OAuth、令牌存储和请求发送。

注意
安装
身份验证
- 个人令牌
- OAuth
发送请求
目录
个人资料
用户
市场
其他端点
- 获取客户端的身份
处理错误和异常
- 授权错误
- 请求错误
示例
- 验证购买代码
版本3中的破坏性更改
贡献者

注意

此API客户端完全可用，但并非一定完成。当然，任何不兼容的更新都将升级为主版本。除此之外，这里有一些你可能想知道的信息。

此客户端不会禁用SSL。它附带证书颁发机构包，并使用此包验证Envato API的SSL证书，而不是依赖于系统上通常不可用的证书。

安装

使用Composer将此包含到您的项目中。它将被自动加载。

composer require baileyherbert/envato

身份验证

个人令牌

使用个人令牌启动新客户端（在build.envato.com创建一个）。

$token = new Herbert\Envato\Auth\Token('Your Personal Token');
$client = new Herbert\EnvatoClient($token);

OAuth

使用OAuth，您必须将用户重定向到Envato的认证屏幕，在那里他们将批准您请求的权限。然后，他们将被重定向回您的应用程序，并带有可以用于获取API令牌的code查询参数。

以下示例演示了一个完整的OAuth保护器，该保护器在用户返回时重定向用户并创建客户端。它还将他们的凭据持久化到PHP会话中，以便可以在未来的请求中重新创建客户端和续订令牌。

// Generate the OAuth object
$oauth = new Herbert\Envato\Auth\OAuth([
    'client_id' => 'Your client id',
    'client_secret' => 'Your client secret',
    'redirect_uri' => 'https://your-redirect-uri.com/',
    'store' => function(string $session) {
        // Example: Save the OAuth credentials to a PHP session
        // This is just a JSON-encoded string that looks like below:
        // {"access_token": "...", "refresh_token": "...", "expires": 1710526960}

        $_SESSION['envato_oauth'] = $session;
    }
]);

// Example: Restore existing OAuth credentials from a PHP session
if (isset($_SESSION['envato_oauth'])) {
    $oauth->load($_SESSION['envato_oauth']);
}

// Get the client (will return NULL if not authenticated)
// This will auto-detect the "code" query parameter on the current request
// If found, it will attempt to create a token and instantiate the client
$client = $oauth->getClient();

// Redirect the user if they're not authorized yet
if (!$client) {
    header("Location: " . $oauth->getAuthorizationUri());
    die;
}

// Example: Get the user's unique Envato Account ID
// This sends a request to the Envato API, so don't call it often!
$userId = $client->getUserId(); // int(1908998)

// Example: Request the user's username
// This sends a request to the Envato API, so don't call it often!
$response = $client->user->username();
$username = $response->username; // string(13) "baileyherbert"

为了让此示例工作，请在build.envato.com网站创建一个新的应用程序。 redirect_uri应直接指向上面代码托管文件，并且在代码和已注册的Envato应用程序中必须完全相同。

以这种方式生成的令牌将在一小时后过期。然而，通过使用上面所示store回调和load()方法，客户端可以自动在后台续订它们。当发生这种情况时，store回调将再次被调用，并带有新的凭据。

发送请求

这是一个获取当前用户用户名的示例请求。目前，它返回一个ResultSet对象；此对象公开一个results属性，该属性是一个包含原始API响应的数组。

$response = $client->user->username();

if (!$response->error) {
    $username = $response->results['username'];

    echo "Logged in as {$username}";
}
else {
    echo "Error: {$response->error}";
}

对于具有变量的端点，您可以将它们作为数组传递。这对于所有端点版本都有效，包括旧版v1和新的v3。

$response = $client->profile->portfolio([
    'username' => 'baileyherbert'
]);

获取请求时间

要确定请求执行所需时间（以秒为单位），您可以参考$response->time属性。

速率限制

如果您正在受到速率限制，客户端将抛出TooManyRequestsException异常。异常实例具有帮助处理速率限制的方法。

use Herbert\Envato\Exceptions\TooManyRequestsException;

try {
    $item = $client->catalog->item(['id' => 1234567]);
}
catch (TooManyRequestsException $e) {
    // Get the number of seconds remaining (float)
    $secondsRemaining = $e->getSecondsRemaining();

    // Get the timestamp for when we can make our next request
    $timestamp = $e->getRetryTime();

    // Sleep until the rate limiting has ended
    $e->wait();
}

自定义请求

如果有一个新的端点尚未包含在此包中，您可以使用客户端上的$request属性手动发送请求，直到它被添加。

为每种请求类型（get、post等）都提供了方法。将路径作为第一个参数传递。将您的POST正文变量作为第二个参数传递，这些变量也将替换路径中标记为{}的变量。

$client->request->get('/v1/market/user:{username}.json', [
  'username' => 'collis'
]);

个人资料

profile类别代表一个公共Envato用户。

列出当前用户的全部集合

$client->profile->collections();

通过ID查找集合

$client->profile->collection(['id' => 12345]);

获取用户的个人资料详情

$client->profile->details(['username' => 'baileyherbert']);

列出用户的徽章

$client->profile->badges(['username' => 'baileyherbert']);

通过网站获取用户的项目

$client->profile->portfolio(['username' => 'baileyherbert']);

获取用户最新的项目

$client->profile->newest(['username' => 'baileyherbert', 'site' => 'codecanyon']);

用户

user类别代表当前认证的用户。

列出作者的销售额

$client->user->sales();

通过购买代码查找销售

$client->user->sale(['code' => '*****']);

列出买家的购买

$client->user->purchases();

通过代码查找买家的购买

$client->user->purchase(['code' => '*****']);

下载买家的购买

$client->user->download(['purchase_code' => '*****']);
$client->user->download(['item_id' => '123456']);

获取私人账户详情

$client->user->details();

获取当前用户的用户名

$client->user->username();

获取当前用户的电子邮件

$client->user->email();

获取用户按月收入

$client->user->earnings();

获取用户的对账单

$client->user->statement([
  'page' => 1,
  'from_date' => '2021-02-01',
  'to_date' => '2022-06-21',
  'type' => 'Sale',
  'site' => 'codecanyon.net'
]);

市场

获取用户总数

$client->market->users();

获取项目总数

$client->market->items();

按网站获取项目总数

$client->market->site(['site' => 'codecanyon']);

其他端点

获取客户端的身份

$identity = $client->getIdentity();

身份将是一个类似以下对象

object(stdClass)#1 (4) {
  ["clientId"]=> NULL
  ["userId"]=> int(1908998)
  ["scopes"]=> array(18) {
    [0]=> string(7) "default"
    [1]=> string(13) "user:username"
    [2]=> string(10) "user:email"
    [3]=> string(12) "user:account"
    [4]=> string(14) "user:financial"
    [5]=> string(17) "purchase:download"
    [6]=> string(12) "sale:history"
    [7]=> string(11) "sale:verify"
  }
  ["ttl"]=> int(315360000)
}

如果您只关心userId属性，可以更轻松地检索它

$userId = $client->getUserId(); // int(1908998)

处理错误和异常

此库中的所有异常都在Herbert\Envato\Exceptions命名空间下。

授权错误

在执行OAuth授权时，您可能会遇到以下异常之一

InvalidTokenException如果提供的令牌不是一个字符串。
MissingPropertyException如果OAuth缺少构造函数参数之一（client_id、client_secret、redirect_uri）。
NotAuthenticatedException如果您在认证之前尝试构造EnvatoClient。

请求错误

在执行请求时，可能会抛出四种可能的异常。

BadRequestException如果缺少必要的参数或参数无效。
UnauthorizedException如果当前授权无效。
TooManyRequestsException如果请求因为高活动而受到限制。
EndpointException如果发生重大错误（API故障、无网络连接等）。

否则，如果请求中发生错误，您可以使用$response->error属性（在成功时为null，在其他情况下为包含错误详情的string）来详细了解错误。

示例

验证购买代码

如果您是作者并希望检查买家提供给您的购买代码，这是一个示例。要使此操作生效，您需要使用个人令牌认证。

$purchase_code = 'purchase code here';
$token = new Herbert\Envato\Auth\Token('Your Personal Token');
$client = new Herbert\EnvatoClient($token);

$response = $client->user->sale(['code' => $purchase_code]);

if (!$response->error) {
    $sale = $response->results;

    $sold_at = $sale['sold_at']; // "2013-04-16T01:59:35+10:00"
    $license = $sale['license']; // "Regular License"
    $supported_until = $sale['supported_until']; // "2013-10-16T00:00:00+10:00"

    $item_id = $sale['item']['id']; // 1252984
    $item_name = $sale['item']['name']; // "Item Name"
    $author_username = $sale['item']['author_username']; // "baileyherbert"

    $num_licenses = $sale['purchase_count']; // 3
    $buyer_username = $sale['buyer']; // "bestbuyerever"

    echo "I got information!";
}
else {
    echo "The code produced an error:\n";
    echo $response->error;
}

版本3中的破坏性更改

如果将包从早期版本升级到v3，有一个单一的重大变化。即user->sales()方法指向了错误的端点。

之前的$client->user->sales()端点已重命名为$client->user->earnings()
新的$client->user->earnings()端点按月列出您的收入
新的$client->user->sales()端点列出您的单独销售

贡献者

特别感谢以下贡献者对维护此包的帮助

baileyherbert / envato

维护者

详细信息