README

Allegro REST API资源的简单接口的第二个版本。基于https://github.com/Wiatrogon/php-allegro-rest-api构建，大部分已重写。

主要区别包括

• 使用HTTPlug / PSR-7进行HTTP通信
• 包含之前缺失的功能（图片上传）
• 支持授权码和客户端凭证流（也可以轻松实现设备流，因为授权现在与主API组件分离了）
• 灵活（自定义头信息，自定义中间件）

0. 安装

PHP Allegro REST API使用HTTPlug，...

如果库依赖于HTTPlug，则需要虚拟包php-http/client-implementation。虚拟包用于声明库需要HTTPlug接口的实现，但不需要指定具体实现。

我推荐使用guzzle6适配器，因此请在安装PHP Allegro REST API库之前运行以下命令

composer require php-http/guzzle6-adapter php-http/message guzzlehttp/psr7

现在你可以运行了

composer require retrowaver/allegro-rest-api-v2

注意，您不需要将HTTP客户端和消息工厂注入到API客户端中 - HTTPlug使用发现自动找到实现。

如果您想明确地将客户端/消息工厂传递给API客户端，您仍然可以这样做（请参阅Api.php构造函数方法）。

1. 注册您的应用

为了使用Allegro REST API，您必须注册您的应用（如果您还没有这样做，请参阅https://developer.allegro.pl/auth/#app）。

2. 授权

首先，您需要获取一个授权令牌。提供了两种不同的令牌管理器，用于不同的授权流类型。使用其中一个获取令牌。

2.1. 授权码流

在此了解它的工作原理： https://developer.allegro.pl/auth/#user

要将其与PHP Allegro REST API一起使用，请执行以下操作

use Retrowaver\Allegro\REST\Token\TokenManager\AuthorizationCodeTokenManager;
use Retrowaver\Allegro\REST\Token\Credentials;

$tokenManager = new AuthorizationCodeTokenManager;
$tokenManager->getUri(
    new Credentials([
        'clientId' => '...',
        'redirectUri' => '...'
    ])
); // show this URI to your user

use Retrowaver\Allegro\REST\Token\Credentials;
$token = $tokenManager->getAuthorizationCodeToken(
    new Credentials([
        'clientId' => '...',
        'clientSecret' => '...',
        'redirectUri' => '...'
    ]),
    $code // code from $_GET
);

2.2. 客户端凭证流

客户端凭证流不需要用户的许可。它主要用于访问公共数据（搜索商品，获取分类树）。更多信息请参阅： https://developer.allegro.pl/auth/#clientCredentialsFlow

use Retrowaver\Allegro\REST\Token\TokenManager\ClientCredentialsTokenManager;
use Retrowaver\Allegro\REST\Token\Credentials;

$tokenManager = new ClientCredentialsTokenManager;
$token = $tokenManager->getClientCredentialsToken(
    new Credentials([
        'clientId' => '...',
        'clientSecret' => '...',
        'redirectUri' => '...'
    ])
);

2.3. 设备流

设备流目前不支持。但您始终可以编写自己的令牌管理器，并使用收到的令牌以通常的方式与API一起使用。更多信息请参阅： https://developer.allegro.pl/auth/#DeviceFlow

3. 刷新令牌

授权码令牌可以刷新（请参阅 https://developer.allegro.pl/auth/#refresh-token）。

use Retrowaver\Allegro\REST\Token\TokenManager\AuthorizationCodeTokenManager;
use Retrowaver\Allegro\REST\Token\Credentials;

$tokenManager = new AuthorizationCodeTokenManager;
$tokenManager->refreshToken(
    new Credentials([
        'clientId' => '...',
        'clientSecret' => '...',
        'redirectUri' => '...'
    ]),
    $token
);

4. 基本用法

4.1. 初始化

use Retrowaver\Allegro\REST\Api;

$api = new Api;
$api->setToken($token); // token received from token manager

4.2. GET方法

// GET https://api.allegro.pl/offers/listing?phrase=dell
$response = $api->offers->listing->get(['phrase' => 'dell']);

4.3. POST方法

// POST https://api.allegro.pl/sale/offers
$response = $api->sale->offers->post($data);

4.4. PUT方法

// PUT https://api.allegro.pl/sale/offers/12345678
$response = $api->sale->offers(12345678)->put($data);

4.5. DELETE方法

// DELETE https://api.allegro.pl/sale/offers/12345678
$response = $api->sale->offers(12345678)->delete();

4.6. 命令

API中的一些资源只能通过命令模式访问（更多信息请参阅https://developer.allegro.pl/command/）。

// PUT https://api.allegro.pl/offers/12345678/change-price-commands/00b8837d-b47e-4f28-9930-29a5cdb10e15
$response = $api->offers(12345678)->{'change-price-commands'}()->put($data);

在上面的示例中，UUID是自动生成的。如果您想，您可以自己生成它，并将其作为参数传递

$response = $api->offers(12345678)->{'change-price-commands'}('some-randomly-generated-uuid')->put($data);

5. 头信息

您可以更改与您的请求一起发送的头信息。您可以根据请求进行更改，或为所有后续请求进行一次更改。

5.1. 为什么要更改头信息？

您可能出于多种原因需要更改标题，主要如下：

• 如果您希望API返回的消息为波兰语（请添加 Accept-Language: pl-PL）
• 如果您想要访问beta方法（更多信息请参阅此处 https://developer.allegro.pl/about/#beta）

5.2. 发送带自定义标题的单个请求

$headers = [
    'Content-Type' => 'application/vnd.allegro.beta.v1+json',
    'Accept' => 'application/vnd.allegro.beta.v1+json'
];

$response = $api->categories->get(null, $headers);

5.3. 为后续请求设置自定义标题

5.3.1. 替换标题

请注意，有一些自定义标题是默认设置的（Content-Type: application/vnd.allegro.public.v1+json 和 Accept: application/vnd.allegro.public.v1+json）。如果您想替换它们，请使用 setCustomHeaders()

$headers = [
    'Content-Type' => 'application/vnd.allegro.beta.v1+json',
    'Accept' => 'application/vnd.allegro.beta.v1+json'
];

$api->setCustomHeaders($headers);

5.3.2. 添加标题

如果您想添加一个或多个自定义标题，请使用 addCustomHeaders()

$headers = [
    'Accept-Language' => 'pl-PL'
];

$api->addCustomHeaders($headers);

请注意，使用此方法时，现有自定义标题不会被替换。

6. 中间件

PHP Allegro REST API具有中间件功能，允许您以任何方式更改请求和响应。

目前，只有一个“真正的”内置中间件 - ImageUploadMiddleware，当发生图像上传请求时，它会更改请求的URI（从标准的 api.allegro.pl 到特定的图像上传 upload.allegro.pl）。

6.1. 创建自己的中间件

您可以通过创建一个实现 Retrowaver\Allegro\REST\Middleware\MiddlewareInterface 的类并将其传递给API构造函数来创建自己的中间件

$middleware = [
    new CustomMiddleware,
    new AnotherCustomMiddleware
];

$api = new Api(null, null, $middleware);

7. 其他事项

7.1. 沙箱

如果您想使用沙箱环境下的API，请使用 Sandbox 而不是 Api，使用 SandboxAuthorizationCodeTokenManager 而不是 AuthorizationCodeTokenManager，使用 SandboxClientCredentialsTokenManager 而不是 ClientCredentialsTokenManager。

7.2. 测试

7.2.1. 单元测试

使用 vendor/bin/phpunit tests --color 运行单元测试。

7.2.2. 沙箱测试

tests-sandbox 包含发送实际HTTP请求到沙箱环境的测试。如果您想运行这些测试，将 tests-sandbox/config.php.dist 重命名为 tests-sandbox/config.php，插入您的沙箱凭证，然后运行 vendor/bin/phpunit tests-sandbox --color。