README

这是一个用 PHP 编写的 GraphQL 客户端，它提供了非常简单但功能强大的查询生成类，使与 GraphQL 服务器交互变得非常简单。

用法

有三种主要方法可以使用此包来生成您的 GraphQL 查询

查询类：一个简单类，映射到 GraphQL 查询。它设计用于轻松快速地操作查询。
QueryBuilder 类：可以用于动态生成 Query 对象的构建类。它设计用于在查询以动态方式构建的情况下使用。
PHP GraphQL-OQM：此包的扩展。它消除了编写任何 GraphQL 查询或参考 API 文档或语法的需要。它从 API 模式生成查询对象，通过 GraphQL 的内省公开的声明，然后可以简单地与之交互。

安装

运行以下命令使用 composer 安装此包

$ composer require carnage/php-graphql-client

对象到查询映射器扩展

为了避免编写任何查询并仅与从您的 API 模式生成的 PHP 对象交互的麻烦，请访问 PHP GraphQL OQM 存储库

查询示例

简单查询

$gql = (new Query('companies'))
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );

此简单查询将检索显示其名称和序列号的全部公司。

完整形式

上一个示例中提供的查询以“缩写形式”表示。缩写形式涉及编写更少的代码行，从而加快了编写查询的过程。下面是上一个示例中相同查询的完整形式示例。

$gql = (new Query())
    ->setSelectionSet(
        [
            (new Query('companies'))
                ->setSelectionSet(
                    [
                        'name',
                        'serialNumber'
                    ]
                )
        ]
    );

如示例所示，缩写形式更易于阅读和编写，通常更倾向于使用与完整形式相比。

除非查询无法用缩写形式表示，否则不应使用完整形式，这种情况只有一个，即我们想要在同一个对象中运行多个查询。

多个查询

$gql = (new Query())
    ->setSelectionSet(
        [
            (new Query('companies'))
            ->setSelectionSet(
                [
                    'name',
                    'serialNumber'
                ]
            ),
            (new Query('countries'))
            ->setSelectionSet(
                [
                    'name',
                    'code',
                ]
            )
        ]
    );

此查询检索所有公司和国家，并为每个显示一些数据字段。它基本上在一个查询对象封装中运行两个（或更多，如果需要）独立查询。

编写多个查询需要以完整形式编写查询对象，以将每个查询表示为父查询对象下的子字段。

嵌套查询

$gql = (new Query('companies'))
    ->setSelectionSet(
        [
            'name',
            'serialNumber',
            (new Query('branches'))
                ->setSelectionSet(
                    [
                        'address',
                        (new Query('contracts'))
                            ->setSelectionSet(['date'])
                    ]
                )
        ]
    );

这个查询更复杂，不仅检索标量字段，还包括对象字段。该查询返回所有公司，显示它们的名称、序列号，以及每个公司的所有分支，显示分支地址，并为每个地址检索所有与该地址关联的合同，显示它们的日期。

带参数的查询

$gql = (new Query('companies'))
    ->setArguments(['name' => 'Tech Co.', 'first' => 3])
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );

这个查询不是通过添加参数来检索所有公司。该查询将检索名称为“Tech Co.”的前3家公司，显示它们的名称和序列号。

带数组参数的查询

$gql = (new Query('companies'))
    ->setArguments(['serialNumbers' => [159, 260, 371]])
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );

这是一个特殊情况的参数查询。在本例中，查询将仅检索序列号在159、260和371之一的公司，显示名称和序列号。

带输入对象参数的查询

$gql = (new Query('companies'))
    ->setArguments(['filter' => new RawObject('{name_starts_with: "Face"}')])
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );

这是参数查询的另一个特殊情况。在本例中，我们设置了一个自定义输入对象“filter”并赋予一些值以限制返回的公司。我们设置filter "name_starts_with"的值为"Face"。此查询将仅检索名称以"Face"开头的公司。

正在构建的RawObject类用于将字符串原样注入查询中。输入到RawObject构造函数中的任何字符串将原样放入查询中，而无需查询类通常执行的任何自定义格式化。

带变量的查询

$gql = (new Query('companies'))
    ->setVariables(
        [
            new Variable('name', 'String', true),
            new Variable('limit', 'Int', false, 5)
        ]
    )
    ->setArguments(['name' => '$name', 'first' => '$limit'])
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );

此查询展示了如何在包中使用变量，以实现由GraphQL标准支持的动态请求。

变量类

变量类是一个不可变类，表示GraphQL标准中的一个变量。其构造函数接收4个参数

name：表示变量名称
type：表示根据GraphQL服务器模式表示的变量类型
isRequired（可选）：表示变量是否必需，默认为false
defaultValue（可选）：表示要分配给变量的默认值。默认值仅在isRequired参数设置为false时才会考虑。

使用别名

$gql = (new Query())
    ->setSelectionSet(
        [
            (new Query('companies', 'TechCo'))
                ->setArguments(['name' => 'Tech Co.'])
                ->setSelectionSet(
                    [
                        'name',
                        'serialNumber'
                    ]
                ),
            (new Query('companies', 'AnotherTechCo'))
                ->setArguments(['name' => 'A.N. Other Tech Co.'])
                ->setSelectionSet(
                    [
                        'name',
                        'serialNumber'
                    ]
                )
        ]
    );

当需要多次以不同参数检索同一对象时，可以在查询构造函数的第二个参数中设置别名。

$gql = (new Query('companies'))
    ->setAlias('CompanyAlias')
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );

也可以通过setter方法设置别名。

使用接口：带内联片段的查询

在查询返回接口类型的字段时，您可能需要使用内联片段来访问底层具体类型上的数据。

此示例展示了如何使用此包生成内联片段

$gql = new Query('companies');
$gql->setSelectionSet(
    [
        'serialNumber',
        'name',
        (new InlineFragment('PrivateCompany'))
            ->setSelectionSet(
                [
                    'boardMembers',
                    'shareholders',
                ]
            ),
    ]
);

查询构建器

QueryBuilder类可以用来动态构建查询对象，这在某些情况下可能很有用。它的工作方式与Query类非常相似，但查询构建被分解为步骤。

这就是如何使用QueryBuilder创建“带输入对象参数的查询”示例

$builder = (new QueryBuilder('companies'))
    ->setVariable('namePrefix', 'String', true)
    ->setArgument('filter', new RawObject('{name_starts_with: $namePrefix}'))
    ->selectField('name')
    ->selectField('serialNumber');
$gql = $builder->getQuery();

与Query类一样，可以使用第二个构造函数参数设置别名。

$builder = (new QueryBuilder('companies', 'CompanyAlias'))
    ->selectField('name')
    ->selectField('serialNumber');

$gql = $builder->getQuery();

或通过setter方法

$builder = (new QueryBuilder('companies'))
    ->setAlias('CompanyAlias')
    ->selectField('name')
    ->selectField('serialNumber');

$gql = $builder->getQuery();

完整形式

与Query类一样，QueryBuilder类可以以完整形式编写，以便在一个查询构建器对象下编写多个查询。下面是一个如何使用QueryBuilder的完整形式的示例

$builder = (new QueryBuilder())
    ->setVariable('namePrefix', 'String', true)
    ->selectField(
        (new QueryBuilder('companies'))
            ->setArgument('filter', new RawObject('{name_starts_with: $namePrefix}'))
            ->selectField('name')
            ->selectField('serialNumber')
    )
    ->selectField(
        (new QueryBuilder('company'))
            ->setArgument('serialNumber', 123)
            ->selectField('name')
    );
$gql = $builder->getQuery();

此查询是前一个示例查询的扩展。它返回所有以名称前缀开头的公司，并返回具有值123的serialNumber的公司，这两个结果都在同一个响应中。

构建客户端

可以通过提供GraphQL端点URL轻松实例化Client对象。

Client构造函数还接收一个可选的"authorizationHeaders"数组，可用于向发送到GraphQL服务器的所有请求中添加授权头。

示例

$client = new Client(
    'http://api.graphql.com',
    ['Authorization' => 'Basic xyz']
);

客户端构造函数还可以接收一个可选的 "httpOptions" 数组，该数组可以覆盖 "authorizationHeaders"，并可用于添加自定义的 Guzzle HTTP 客户端请求选项。

示例

$client = new Client(
    'http://api.graphql.com',
    [],
    [ 
        'connect_timeout' => 5,
        'timeout' => 5,
        'headers' => [
            'Authorization' => 'Basic xyz'
            'User-Agent' => 'testing/1.0',
        ],
        'proxy' => [
                'http'  => 'tcp://localhost:8125', // Use this proxy with "http"
                'https' => 'tcp://localhost:9124', // Use this proxy with "https",
                'no' => ['.mit.edu', 'foo.com']    // Don't use a proxy with these
        ],
        'cert' => ['/path/server.pem', 'password']
        ...
    ]
);

您可以使用自己的预配置 HTTP 客户端，该客户端实现了 PSR-18 接口。

示例

$client = new Client(
    'http://api.graphql.com',
    [],
    [],
    $myHttpClient
);

运行查询

结果格式化

使用 GraphQL 客户端运行查询并获取对象结构的结果

$results = $client->runQuery($gql);
$results->getData()->companies[0]->branches;

或者获取数组结构的结果

$results = $client->runQuery($gql, true);
$results->getData()['companies'][1]['branches']['address'];

将变量传递给查询

运行包含变量的查询需要将一个关联数组传递给 runQuery 方法，该数组将变量名（键）映射到变量值（值）。以下是一个示例

$gql = (new Query('companies'))
    ->setVariables(
        [
            new Variable('name', 'String', true),
            new Variable('limit', 'Int', false, 5)
        ]
    )
    ->setArguments(['name' => '$name', 'first' => '$limit'])
    ->setSelectionSet(
        [
            'name',
            'serialNumber'
        ]
    );
$variablesArray = ['name' => 'Tech Co.', 'first' => 5];
$results = $client->runQuery($gql, true, $variablesArray);

突变

突变遵循 GraphQL 中查询的相同规则，它们选择返回对象上的字段，接收参数，并且可以有子字段。

以下是如何构建和运行突变的示例

$mutation = (new Mutation('createCompany'))
    ->setArguments(['companyObject' => new RawObject('{name: "Trial Company", employees: 200}')])
    ->setSelectionSet(
        [
            '_id',
            'name',
            'serialNumber',
        ]
    );
$results = $client->runQuery($mutation);

突变可以像查询一样由客户端运行。

带有变量的突变示例

突变可以像查询一样使用变量。以下是如何使用变量将输入对象动态传递给 GraphQL 服务器的示例

$mutation = (new Mutation('createCompany'))
    ->setVariables([new Variable('company', 'CompanyInputObject', true)])
    ->setArguments(['companyObject' => '$company']);

$variables = ['company' => ['name' => 'Tech Company', 'type' => 'Testing', 'size' => 'Medium']];
$client->runQuery(
    $mutation, true, $variables
);

以下是突变及其传递的变量

mutation($company: CompanyInputObject!) {
  createCompany(companyObject: $company)
}
{"company":{"name":"Tech Company","type":"Testing","size":"Medium"}}

实时 API 示例

GraphQL Pokemon 是一个非常酷的公共 GraphQL API，可用于检索宝可梦数据。该 API 在网络上公开提供，我们将使用它来演示该客户端的功能。

Github 仓库链接： https://github.com/lucasbento/graphql-pokemon

API 链接： https://graphql-pokemon.now.sh/

此查询检索任何宝可梦的进化和它们的攻击

query($name: String!) {
  pokemon(name: $name) {
    id
    number
    name
    evolutions {
      id
      number
      name
      weight {
        minimum
        maximum
      }
      attacks {
        fast {
          name
          type
          damage
        }
      }
    }
  }
}

这就是如何使用查询类编写此查询并使用客户端运行

$client = new Client(
    'https://graphql-pokemon.now.sh/'
);
$gql = (new Query('pokemon'))
    ->setVariables([new Variable('name', 'String', true)])
    ->setArguments(['name' => '$name'])
    ->setSelectionSet(
        [
            'id',
            'number',
            'name',
            (new Query('evolutions'))
                ->setSelectionSet(
                    [
                        'id',
                        'number',
                        'name',
                        (new Query('attacks'))
                            ->setSelectionSet(
                                [
                                    (new Query('fast'))
                                        ->setSelectionSet(
                                            [
                                                'name',
                                                'type',
                                                'damage',
                                            ]
                                        )
                                ]
                            )
                    ]
                )
        ]
    );
try {
    $name = readline('Enter pokemon name: ');
    $results = $client->runQuery($gql, true, ['name' => $name]);
}
catch (QueryError $exception) {
    print_r($exception->getErrorDetails());
    exit;
}
print_r($results->getData()['pokemon']);

或者，这就是如何使用 QueryBuilder 类生成此查询

$client = new Client(
    'https://graphql-pokemon.now.sh/'
);
$builder = (new QueryBuilder('pokemon'))
    ->setVariable('name', 'String', true)
    ->setArgument('name', '$name')
    ->selectField('id')
    ->selectField('number')
    ->selectField('name')
    ->selectField(
        (new QueryBuilder('evolutions'))
            ->selectField('id')
            ->selectField('name')
            ->selectField('number')
            ->selectField(
                (new QueryBuilder('attacks'))
                    ->selectField(
                        (new QueryBuilder('fast'))
                            ->selectField('name')
                            ->selectField('type')
                            ->selectField('damage')
                    )
            )
    );
try {
    $name = readline('Enter pokemon name: ');
    $results = $client->runQuery($builder, true, ['name' => $name]);
}
catch (QueryError $exception) {
    print_r($exception->getErrorDetails());
    exit;
}
print_r($results->getData()['pokemon']);

运行原始查询

尽管这不是此包的主要目标，但它支持运行原始字符串查询，就像其他任何客户端一样，只需在 Client 类中使用 runRawQuery 方法。以下是如何使用它的示例

$gql = <<<QUERY
query {
    pokemon(name: "Pikachu") {
        id
        number
        name
        attacks {
            special {
                name
                type
                damage
            }
        }
    }
}
QUERY;

$results = $client->runRawQuery($gql);

carnage / php-graphql-client

维护者

详细信息

README

用法

安装

对象到查询映射器扩展

查询示例

简单查询

完整形式

多个查询

嵌套查询

带参数的查询

带数组参数的查询

带输入对象参数的查询

带变量的查询

变量类

使用别名

使用接口：带内联片段的查询

查询构建器

完整形式

构建客户端

运行查询

结果格式化

将变量传递给查询

突变

带有变量的突变示例

实时 API 示例

运行原始查询