README

PHP 客户端用于操作 MyTarget API (v1/v2)。

通过 composer 安装

composer require dsl/my-target-sdk

如何使用它？

$clients = new ClientOperator(...);
$client = $clients->create(new AdditionalUserInfo("cl1"));

$campaigns = new CampaignOperator(...);

$targeting = new CampaignTargeting();
$targeting->setAge(range(20, 30));
$targeting->setSex(Sex::female());

$createCampaign = new CreateCampaign("awesome campaign", new PackageId(83), $targeting);
$createCampaign->setStatus(Status::active());

$createdCampaign = $campaigns->forClient($client->getUsername())->create($createCampaign);

也可以不使用 *Operator 类，而是手动编写查询。（更多信息下面）

5 分钟快速启动

要使上面的示例生效，需要为 ClientOperator 和 CampaignOperator 创建依赖关系图。这两个操作员都依赖于 Client 和 Mapper 组件。对于沙箱，可以通过以下方式实例化带有其依赖关系的客户端：

namespace sandbox;

use MyTarget\Client;
use GuzzleHttp\Psr7\Uri;
use GuzzleHttp\Client as GuzzleClient;
use MyTarget\Transport\GuzzleHttpTransport;
use MyTarget\Transport\Middleware\HttpMiddlewareStack;
use MyTarget\Transport\Middleware\HttpMiddlewareStackPrototype;
use MyTarget\Transport\Middleware\Impl\CallbackMiddleware;
use MyTarget\Transport\Middleware\Impl\ResponseValidatingMiddleware;
use MyTarget\Token\Token;
use Psr\Http\Message\RequestInterface;

$baseUri = new Uri('https://target.my.com');
$token = new Token("ACCESS_TOKEN", "bearer", new \DateTime(), ""); // библиотека также в состоянии управлять набором токенов в любом типе хранилища (а также получать новые и рефрешить)

$http = new GuzzleHttpTransport(new GuzzleClient());
$httpStack = HttpMiddlewareStackPrototype::newEmpty($http);
$httpStack->push(new ResponseValidatingMiddleware());

// подпишем все запросы заранее полученным токеном (также можно использовать более сложный TokenGrantMiddleware, который способен хранить токен в любых хранилищах, обновлять и получать его)
$accessToken = "foo bar";
$httpStack->push(new CallbackMiddleware(function (RequestInterface $req, HttpMiddlewareStack $stack, $context = null) use ($accessToken) {
    $req = $req->withHeader('Authorization', sprintf('Bearer %s', $accessToken));
    return $stack->request($req, $context);
}));

$client = new Client(new RequestFactory($baseUri), $httpStack);

这将创建一个最简单的客户端，可以自动使用提供的令牌签发所有请求并返回数组形式的响应（如果发生错误，则抛出异常）。除此之外，还有其他功能，例如管理令牌和监控 API 限制。（更多信息在高级功能）为沙箱创建映射器要简单得多

$autoloader = require_once __DIR__ . '/../vendor/autoload.php'; // когда подключается автолоадер нужно присвоить его переменной (этот код будет в самом начале)
AnnotationRegistry::registerLoader([$autoloader, 'loadClass']); // нужно для правильной работы doctrine/annotations

$mapper = \MyTarget\simpleMapper($debug = true);

现在可以创建 ClientOperator 并获取客户列表

$clients = new ClientOperator($client, $mapper);

var_dump($clients->all());

高级功能和用法

待办事项

它是如何工作的？

整个项目分为几个组件

客户端（传输）- 与网络通信相关的所有内容
映射器 - 用于将 API 响应映射到对象
操作员集合 - 将所有可能的发送和接收值类型化为对象

客户端使用一组中间件对象，这些对象可以读取/修改 API 请求和响应。这允许轻松地将与请求处理相关的不同功能分解到不同的实体中。例如，有 LimitingMiddleware、ClientGrantMiddleware 和 ResponseValidatingMiddleware。它们在处理 HTTP 消息的水平上相似，但在语义上没有任何共同点。

映射器执行简单的功能，将 API 响应映射到类型化的对象：`$mapper->hydrateNew('Foo', $jsonObject)` 将返回一个 Foo 实例，其中对象的字段将根据 Field(name="api_field_name", type="string") 类型的注释进行填充。

操作员连接上述两个组件，并允许在更高层次上操作 API。但是，如果您不喜欢使用对象并且对任意数组数据感到满意，则可以直接使用客户端。这样，您仍然可以获得配置好的 OAuth2 身份验证，将错误的 API 响应转换为异常，并控制查询限制。

HttpMiddleware

使用 HttpMiddlewareStack 进行网络操作。此堆栈包含所有堆叠在一起的 HTTP 请求和响应处理器。一个处理器的示例如下

class MyMiddleware implements HttpMiddleware
{
    public function request(RequestInterface $request, HttpMiddlewareStack $stack, array $context = null)
    {
        return $stack->request($request, $context);
    }

此中间件只是调用下一个中间件。此调用始终返回 Psr7\ResponseInterface 类型的对象（或者抛出异常）。以下是一个更有用的中间件示例，它可以记录整个 HTTP 交互

class LoggingMiddleware implements HttpMiddleware
{
    public function request(RequestInterface $request, HttpMiddlewareStack $stack, array $context = null)
    {
        try {
            $response = $stack->request($request, $context);
            log($request, $response);
            return $response;
        } catch (RequestException $e) {
            logError($request, $e);
            throw $e;
        }
    }
}

异常层次结构

这个库中的所有异常都遵循以下层次结构

- MyTarget\Exception\MyTargetException - Интерфейс (маркер) всех исключений этой библиотеки (если есть необходимость "не выпускать" никаких исключений от СДК, то нужно ловить этот тип исключения)
  - MyTarget\Transport\Exception\TransportException - thrown during request transferring phase
    - MyTarget\Transport\Exception\RequestException
      - MyTarget\Transport\Exception\ClientErrorException
      - MyTarget\Transport\Exception\ConnectException
      - MyTarget\Transport\Exception\ServerErrorException
      - MyTarget\Transport\Exception\TooManyRedirectsException
      - MyTarget\Token\Exception\TokenRequestException
        - MyTarget\Token\Exception\TokenLimitReachedException
        - MyTarget\Token\Exception\TokenDeletedException
      - MyTarget\Limiting\Exception\ThrottleException - thrown before the request if you've reached the rate limit, or after the response is parsed and it contains a 429 code
  - MyTarget\Exception\DecodingException - thrown during response decoding phase

除此之外，它们还被分为两种类型： Dsl\MyTarget\Exception\ApiException 和 Dsl\MyTarget\Transport\Exception\NetworkException。

如何贡献

为了提出您的更改，您可以创建这个仓库的分支，并提交带有描述更改的任意消息的PR。

dsl / my-target-sdk

维护者

详细信息