README

简介

此软件包包含AudiencePlayer API客户端库，并简化了与您自己的管理界面和/或后台办公室的API集成。

• API集成
• 定制前端应用程序开发。

尽管不是必需的，但为了优化使用此包，建议您有一个现有的AudiencePlayer账户，并已颁发OAuth2客户端凭据。

要求

要使用PHP的AudiencePlayer API客户端库，必须满足以下要求

• PHP >= 7.1（推荐 >= 7.3）
• PHP JSON扩展
• PHP cURL扩展
• 最新的OpenSSL（或其他SSL/TLS工具包）

安装

使用Composer安装此软件包是最简单的方法Composer

    $ composer require audienceplayer/audienceplayer-api-client-php

或者，您可以下载此软件包并包含文件AutoLoader.php以集成此软件包

    require 'src/AudiencePlayer/AudiencePlayerApiClient/AutoLoader.php';

入门

实例化

首先实例化API客户端

    $clientId = 'yourOAuthClientId';
    $clientSecret = 'yourOAuthClientSecret';
    $projectId = 123456;
    $apiBaseUrl = 'https://api.example.com';

    # Instantiate with your clientId, clientSecret, projectId and apiBaseUrl
    $apiClient = AudiencePlayerApiClient::init(
        $clientId,
        $clientSecret,
        $projectId,
        $apiBaseUrl
    );

通过适当的机制进行认证以获得对特定用户（或作为OAuth2管理员客户端）的访问权限

    # Pre-existing bearerToken that you may have cached for given user    
    $bearerToken = 'eYarTl93Fas3...';
    # User-ID or E-mail address of the user for whom you are validating/creating a token
    $userEmail = 'info@example.com';
    # When validating with only an e-mail address, the user may be auto-registered if non-existent
    $isAutoRegister = true;
 
    # Compare new token with pre-existing token and update your stored token if necessary 
    $newBearerToken = $apiClient->hydrateValidatedOrRenewedBearerTokenForUser(
        $userId,
        $userEmail,
        $userArgs,
        $bearerToken,
        $isAutoRegister
    );

执行查询和变异

GraphQL查询操作的示例

    # Example of fetching an article with ID=123, and requesting properties name and type
    $result = $apiClient->query
        ->Article(123)                                              # required argument $id=123
        ->properties(['name', 'type'])                              # explicitly ask for given properties
        ->execute();

    # Example of fetching an articles list
    $result = $apiClient->query
        ->ArticleList()
        ->paginate(25, 0)                                           # with limit 25 and offset 0
        ->arguments(['category_id' => 456])                         # fetched all articles part of category with id 456
        ->properties(['id', 'name', 'metas' => ['key', 'value']])   # explicitly ask for given properties
        ->sort(                                                     # sort results by id in descending order
            'id',
            $apiClient:GRAPHQL_OPERATION_SORT_DIRECTION_DESC
        )
        ->execute();

    # Example of searching for specific articles
    $result = $apiClient->query
        ->ArticleList()
        ->search('foobar')                                          # search for articles with matching metadata
        ->properties(['id', 'name', 'metas{key,value}'])            # explicitly ask for given properties
        ->sort(                                                     # sort results by name in descending order
            'name',
            $apiClient:GRAPHQL_OPERATION_SORT_DIRECTION_ASC
        )
        ->execute();

GraphQL变异操作的示例

    # Example of updating user details
    $result = $apiClient->mutation
        ->UserDetails()
        ->arguments(['email' => 'info2@example.com'])               # update with given arguments
        ->execute();

您可以使用以下辅助工具轻松处理操作结果对象

    # Inspect the result
    $result->isSuccessful();                        # result was successfully retrieved and does not contain any errors
    $result->hasErrors();                           # result contains errors
    $result->getErrors();                           # obtain a list of errors

    # Access result properties
    $result->data;                                  # the returned data
    $result->getData();
    
    # Inspect the last graphql operation, which may be helpful for debugging purposes
    $result->getOperationQuery();                   # the executed raw graphQL query, e.g. "query{UserDetails{id,email}}"
    $result->getOperationVariables();               # the used graphQL variables (if applicable), e.g. "{id:1}"

自定义查询和变异

您还可以执行自定义GraphQL查询和变异。有关GraphQL语法的更多信息，请参阅graphql.org。

    $operation = 'query Article($articleId:Int) {
                  CustomArticleQuery: Article (id:$articleId) {id name}
              }
    ';

    $result = $apiClient->executeRawGraphQLCall(
        Globals::OAUTH_SCOPE_USER,                  # the oauth-scope you wish to address the api with
        $operation,                                 # raw GraphQL operation (query/mutation) 
        ['articleId' => 1],                         # variables for the operation (if necessary)
        true,                                       # execute as POST request (false for GET)
        true,                                       # retrieve result as parsed object (false for raw JSON)
        'Article',                                  # operation name
        $bearerToken                                # your stored/saved OAuth bearer token
    );

    $result = $apiClient->executeRawGraphQLCall(
        Globals::OAUTH_SCOPE_USER,                  # The oauth-scope you wish to address the api with
        'query{Article(id:1){id,name}}',            # simple raw GraphQL operation without variables 
        [],                                         # the variables for the operation (if necessary)
        true,                                       # execute as POST request (false for GET)
        true,                                       # retrieve result as parsed object (false for raw JSON)
        'Article',                                  # operation name
        $bearerToken                                # your stored/saved OAuth bearer token
    );

测试

您可以通过执行以下操作来运行单元和静态测试

    $ composer run test

或单独运行它们

    $ ./vendor/bin/phpunit
    $ ./vendor/bin/phpstan

许可证

BSD（伯克利软件发行版）许可证。版权所有（c）2020，AudiencePlayer

支持

联系方式

• www.audienceplayer.com
• support@audienceplayer.com