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'
                    ]
                )
        ]
    );

在需要多次以不同参数检索相同对象的情况下，可以在Query构造函数的第二个参数中设置别名。

$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://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']
        ...
    ]
);

可以使用实现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);

gmostafa / php-graphql-client

维护者

详细信息

README

使用方法

安装

对象到查询映射扩展

查询示例

简单查询

完整形式

多个查询

嵌套查询

带有参数的查询

带有数组参数的查询

带有输入对象参数的查询

带变量的查询

变量类

使用别名

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

查询构建器

完整形式

构建客户端

运行查询

结果格式化

向查询传递变量

变更

带有变量的变异示例

实时API示例

运行原始查询