README

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

使用方法

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

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

安装

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

$ composer require gmostafa/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']
);

Client构造函数还接收一个可选的“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://:8125', // Use this proxy with "http"
                'https' => 'tcp://:9124', // Use this proxy with "https",
                'no' => ['.mit.edu', 'foo.com']    // Don't use a proxy with these
        ],
        'cert' => ['/path/server.pem', 'password']
        ...
    ]
);

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

示例

$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);

mxneyio / php-graphql-client

维护者

详细信息

README

使用方法

安装

对象到查询映射器扩展

查询示例

简单查询

完整形式

多个查询

嵌套查询

带参数的查询

带数组参数的查询

带输入对象参数的查询

带变量的查询

变量类

使用别名

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

查询构建器

完整形式

构建客户端

运行查询

结果格式化

向查询传递变量

突变

带变量突变示例

实时 API 示例

运行原生查询