README

要求

PHP 7.2或更高版本
ext-json
ext-curl
ext-mbstring

可选

ext-openssl用于AccessTokenContainerEncryptedFile
PDO, sqlite, mysql用于AccessTokenContainerSqlite/AccessTokenContainerPDO

关于版本号的说明

SDK的版本号非常重要。它看起来像是3.<major>.<minor>，例如3.0.1。当您将SDK包含到您的composer配置中时，强烈建议将主版本设置为固定的，例如

"require": {
    "serwisant/serwisant-api": "3.0.*"
},

这是因为类型查询和突变。如果模式发生变化，传递给查询和突变的参数也会随之变化。这可能是新的必需参数，甚至参数的顺序也可能改变。在这种情况下，SDK将发布带有递增主版本的版本。如果您决定升级，它可能会破坏您的应用程序。

警告：

这里有一个例外。内部模式不是供公众消费的。破坏性变更将不遵循上述规则。

使用方法

1. 访问令牌和模式工厂。

首先，准备一个SerwisantApi\Api实例以供以后使用。它应该在整个应用程序中共享。您可以将它设置为单例结果，将其放入依赖注入容器中等。不要创建多个SerwisantApi\Api实例 - 这是无用的且效率低下。

use Serwisant\SerwisantApi;

// get own client and secret by creating an application via webpage
$access_token = new SerwisantApi\AccessTokenOauth('client', 'secret', 'public', (new SerwisantApi\AccessTokenContainerEncryptedFile('some_string_as_encryption_key')));

$api = new SerwisantApi\Api();
$api->setAccessToken($access_token);

AccessTokenOauth的第四个参数是访问令牌缓存。

它是可选的，但出于性能原因，强烈推荐使用它，因为它在请求之间持久化访问令牌，直到它过期，从而避免为每个HTTP请求创建新的令牌。查看其他缓存容器

SerwisantApi\AccessTokenContainerEncryptedFile - 在加密的本地文件中缓存数据，可用于单服务器应用程序，该应用程序可以访问本地文件系统
SerwisantApi\AccessTokenContainerFile - 在纯文本本地文件中缓存数据，可用于单服务器应用程序，该应用程序可以访问本地文件系统。请注意 - 在共享托管环境中使用它是不安全的，因为明文访问令牌可能会保存在其他用户可访问的/tmp目录中。
SerwisantApi\AccessTokenContainerSession - 在会话容器中，它应仅与AccessTokenOauthUserCredentials一起使用，并存储特定于用户的访问令牌（使用登录和密码获取） - 请勿仅用于密钥-秘密访问令牌。
SerwisantApi\AccessTokenContainerSqlite - 基于SQLite数据库的缓存，易于设置。需要PDO和php_pdo_sqlite扩展。当使用此容器时，您不必担心数据库 - 它将在首次使用时自动创建。
SerwisantApi\AccessTokenContainerPDO - 通用PDO令牌容器。请注意：您必须在首次使用之前创建数据库/表。表模式

CREATE TABLE IF NOT EXISTS access_token
(
    namespace varchar(64)  NOT NULL,
    token     varchar(255) NOT NULL,
    refresh   varchar(255),
    expiry    int(11)      NOT NULL,
    PRIMARY KEY (namespace)
);

...自行构建，使用SerwisantApi\AccessTokenContainer抽象类

请注意 - 如果您为每个请求创建太多的访问令牌，则您的应用程序可能会被禁止。

2. 带内查询的基本示例

将查询字符串放入变量中，然后直接执行它。最重要的是，在您的查询中为每个请求的对象添加魔法字段__typename。它从GraphQL服务器获取对象名称并将其包装在PHP类中。当您获得结果时，它将是一个具有所有属性等的PHP对象（或对象数组）。

任何类型的缺少魔法字段将导致异常。

use Serwisant\SerwisantApi;

/* @var SerwisantApi\Api $api */

/* please note __typename at each type - it's required for proper typecast */
$query = '
query($token: String!) {
    repairByToken(token: $token) {
      __typename
      displayName
      status {
        __typename
        displayName
      }
    }
}';

/* @var SerwisantApi\Types\SchemaPublic\Repair $repair */
$repair = $api->publicQuery()->newRequest()->set($query, ['token' => 'abc-def'])->execute()->fetch();
 
echo $repair->displayName;
echo $repair->status->displayName;

3. 准备好的查询和突变

上述示例也可以用其他方式调用。

请在应用程序的根目录下创建一个名为 queries\SchemaPublic 的文件夹。

接下来，请将查询字符串的内容放入 queries\SchemaPublic\repairByToken.graphql 文件中。文件名很重要。它必须是schema中看到的精确查询名称。文件扩展名必须是 .graphql。

这正是你在第1个例子中分配给变量的那个查询。

use Serwisant\SerwisantApi;

/* @var SerwisantApi\Api $api */

// tell SerwisantApi\Api where to look for files with queries, mutations, etc. It can be done once, in 1. example.
$api->addLoadPath('/full/path/to/queries/SchemaPublic');

/* @var SerwisantApi\Types\SchemaPublic\PublicQuery $query */
$query = $api->publicQuery();

/* @var SerwisantApi\Types\SchemaPublic\Repair $repair */
$repair = $query->repairByToken('abc-def'); // abc-def is a token form repair fetched from user input

echo $repair->displayName;
echo $repair->status->displayName;

你可能想问：为什么SDK不提供包含所有可用查询和突变文件的文件？

这是因为我们不知道你想要从schema中获取哪些字段/对象。限制获取数据的可能性是GraphQL最重要的功能之一。使用预定义的查询文件，你会失去自己决定的机会。

提示使用GraphQL语法，你可以在单个 .graphql 文件中拥有多个查询变体，并使用查询变量选择正确的一个。看下面的例子。让我们有 repairByToken.graphql。注意多个 repairByToken 和 @include(if: ..) 标签。

query repairByToken($token: String!, $basic: Boolean = false, $complete: Boolean = false) {
    repairByToken(token: $token) @include(if: $basic) {
        __typename
        status {
            __typename
            displayName
        }
    }
    repairByToken(token: $token) @include(if: $complete) {
        __typename
        rma
        serial
        vendor
        model
    }
}

调用以获取仅维修状态（查询将快速执行

$query = $api->publicQuery();
$repair = $query->repairByToken('abc-def', ['basic' => true])

调用以获取有关维修的复杂信息（查询执行可能需要更长时间)

$query = $api->publicQuery();
$repair = $query->repairByToken('abc-def', ['complete' => true])

4. 批处理查询

GraphQL的一个酷功能是能够在单个请求中放入多个查询。你需要为每个查询提供唯一的名称，一旦执行，结果将包含两个响应。

使用批处理以提高性能。批处理查询可以减少HTTP流量。

use Serwisant\SerwisantApi;

/* @var SerwisantApi\Api $api */

/* please note __typename at each type - it's required for proper typecast */
$query = '
query($token: String!) {
  repair: repairByToken(token: $token) {
    __typename
    displayName
  }
  me: viewer {
    __typename
    employee {
      __typename
      displayName
    }
  } 
}';

$result = $api->publicQuery()->newRequest()->set($query, ['token' => 'abc-def'])->execute();

/* @var SerwisantApi\Types\SchemaPublic\Repair $repair */
$repair = $result->fetch('repair');

/* @var SerwisantApi\Types\SchemaPublic\Viewer $me */
$me = $result->fetch('me');

echo $repair->displayName;
echo $me->subscriber;

提示你可以将批处理查询（假设是上面的查询）放入自定义名称下的查询文件夹，并按以下方式调用

$result = $api->publicQuery()->newRequest()->setFile('myBatchedQuery.graphql', ['token' => $secret_token])->execute();
$repair = $result->fetch('repair');
$me = $result->fetch('me');

变更日志

请参阅 CHANGELOG 中的变更日志

贡献

欢迎提交拉取请求。

不要编辑或更新 src/Serwisant/SerwisantApi/Types 中的任何文件 - 该目录中的所有文件/类都是自动生成的，更改将被覆盖。

要生成缺失的类型、查询和突变，请使用 bin/introspection.php 脚本

php ./bin/introspection.php

开发

SDK作为packagist.org上的composer包提供

更新 composer.json 以新版本
将更改提交到master
git tag 3.0.x
git push origin --tags

有两个环境变量可以用于测试/开发与开发服务器进行交互的SDK。设置

OAUTH_URL 为例如 http://127.0.0.1:3000/oauth/token 以更改OAuth令牌端点
OAUTH_REVOKE_URL 为例如 http://127.0.0.1:3000/oauth/revoke 以更改OAuth令牌撤销端点
GRAPHQL_URL 为例如 http://127.0.0.1:3000/graphql 以更改GraphQL schemas的基础地址。

许可

Apache许可证请参阅LICENCE以获取完整的许可信息。

作者

Arkadiusz Kuryłowicz <sms(at)kurylowicz.info>

serwisant / serwisant-api

维护者

详细信息