README

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

用法

使用此包生成GraphQL查询主要有3种主要方式

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

安装

运行以下命令使用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);

socialengineers / php-graphql-client

维护者

详细信息

README

用法

安装

对象到查询映射扩展

查询示例

简单查询

完整形式

多个查询

嵌套查询

带有参数的查询

带有数组参数的查询

带有输入对象参数的查询

带有变量的查询

变量类

使用别名

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

查询构建器

完整形式

构建客户端

运行查询

结果格式化

向查询传递变量

变体

带变量的变异示例

实时API示例

运行原始查询