README

这是一个基于JavaScript 参考实现的GraphQL规范的PHP实现。

要求

PHP版本 >= 7.1
ext-mbstring

安装

运行以下命令通过Composer安装包

composer require digiaonline/graphql

示例

以下是一个简单的示例，演示了如何从一个包含星战主题模式（SDL）的GraphQL模式文件（关于模式定义本身，请见下文）构建可执行的方案。在这个示例中，我们使用该SDL构建一个可执行的方案，并使用它查询英雄的名字。该查询的结果是一个类似于我们执行的查询的结构关联数组。

use Digia\GraphQL\Language\FileSourceBuilder;
use function Digia\GraphQL\buildSchema;
use function Digia\GraphQL\graphql;

$sourceBuilder = new FileSourceBuilder(__DIR__ . '/star-wars.graphqls');

$schema = buildSchema($sourceBuilder->build(), [
    'Query' => [
        'hero' => function ($rootValue, $arguments) {
            return getHero($arguments['episode'] ?? null);
        },
    ],
]);

$result = graphql($schema, '
query HeroNameQuery {
  hero {
    name
  }
}');

\print_r($result);

上面的脚本产生了以下输出

Array
(
    [data] => Array
    (
        [hero] => Array
        (
            [name] => "R2-D2"
        )
        
    )
    
)

本例中使用的GraphQL模式文件包含以下内容

schema {
    query: Query
}

type Query {
    hero(episode: Episode): Character
    human(id: String!): Human
    droid(id: String!): Droid
}

interface Character {
    id: String!
    name: String
    friends: [Character]
    appearsIn: [Episode]
}

type Human implements Character {
    id: String!
    name: String
    friends: [Character]
    appearsIn: [Episode]
    homePlanet: String
}

type Droid implements Character {
    id: String!
    name: String
    friends: [Character]
    appearsIn: [Episode]
    primaryFunction: String
}

enum Episode { NEWHOPE, EMPIRE, JEDI }

创建模式

为了对您的GraphQL API执行查询，您首先需要定义API的结构。这是通过创建一个模式来完成的。有两种方法可以做到这一点，您可以使用SDL或编程方式。但是，我们强烈建议您使用SDL，因为它更容易处理。要从SDL创建可执行的方案，您需要调用buildSchema函数。

buildSchema函数接受三个参数

$source 模式定义（SDL）作为Source实例
$resolverRegistry 包含所有解析器的关联数组或ResolverRegistry实例
$options 构建方案选项，包括自定义类型和指令

要创建Source实例，您可以使用提供的FileSourceBuilder或MultiFileSourceBuilder类。

解析器注册

解析器注册表本质上是一个扁平映射，类型名称作为其键，相应的解析器实例作为其值。对于较小的项目，您可以使用关联数组和lambda函数来定义您的解析器注册表。然而，在较大的项目中，我们建议您实现自己的解析器。您可以在解析器部分了解更多关于解析器的信息。

关联数组示例

$schema = buildSchema($source, [
    'Query' => [
        'hero' => function ($rootValue, $arguments) {
            return getHero($arguments['episode'] ?? null);
        },
    ],
]);

解析器类示例

$schema = buildSchema($source, [
    'Query' => [
        'hero' => new HeroResolver(),
    ],
]);

解析器中间件

如果您在多个解析器中编写相同的逻辑，应考虑使用中间件。解析器中间件允许您高效地管理多个解析器之间的功能。

中间件之前示例

$resolverRegistry = new ResolverRegristry([
    'Query' => [
        'hero' => function ($rootValue, $arguments) {
            return getHero($arguments['episode'] ?? null);
        },
    ],
], [
    'middleware' => [new BeforeMiddleware()],
]);
$schema = buildSchema($source, $resolverRegistry);

class BeforeMiddleware implements ResolverMiddlewareInterface
{
    public function resolve(callable $resolveCallback, $rootValue, array $arguments, $context, ResolveInfo $info) {
        $newRootValue = $this->doSomethingBefore();
        return $resolveCallback($newRootValue, $arguments, $context, $info);
    }
}

中间件之后示例

$resolverRegistry = new ResolverRegristry([
    'Query' => [
        'hero' => function ($rootValue, $arguments) {
            return getHero($arguments['episode'] ?? null);
        },
    ],
], [
    'middleware' => [new AfterMiddleware()],
]);
$schema = buildSchema($source, $resolverRegistry);

class AfterMiddleware implements ResolverMiddlewareInterface
{
    public function resolve(callable $resolveCallback, $rootValue, array $arguments, $context, ResolveInfo $info) {
        $result = $resolveCallback($rootValue, $arguments, $context, $info);
        $this->doSomethingAfter();
        return $result;
    }
}

解析器中间件可以用于许多事情；例如日志记录、输入清理、性能测量、授权和缓存。

如果您想了解更多关于模式的信息，可以参考规范。

执行

查询

要针对您的模式执行查询，您需要调用graphql函数，并传递您的模式和您要执行的查询。您也可以通过更改查询来运行mutations和subscriptions。

$query = '
query HeroNameQuery {
  hero {
    name
  }
}';

$result = graphql($schema, $query);

如果您想了解更多关于查询的信息，可以参考规范。

解析器

模式中的每个类型都与一个解析器相关联，允许解析实际值。然而，大多数类型不需要自定义解析器，因为它们可以使用默认解析器进行解析。通常，这些解析器是lambda函数，但您也可以通过扩展AbstractTypeResolver或AbstractFieldResolver来定义自己的解析器。或者，您也可以直接实现ResolverInterface。

解析器函数接收四个参数

$rootValue 父对象，在某些情况下也可以是null
$arguments 查询中字段提供的参数
$context 一个传递给每个解析器的值，可以包含重要的上下文信息
$info 包含与当前查询相关的特定字段信息的值

lambda函数示例

function ($rootValue, array $arguments, $context, ResolveInfo $info): string {
    return [
        'type'       => 'Human',
        'id'         => '1000',
        'name'       => 'Luke Skywalker',
        'friends'    => ['1002', '1003', '2000', '2001'],
        'appearsIn'  => ['NEWHOPE', 'EMPIRE', 'JEDI'],
        'homePlanet' => 'Tatooine',
    ];
}

类型解析器示例

class HumanResolver extends AbstractTypeResolver
{
    public function resolveName($rootValue, array $arguments, $context, ResolveInfo $info): string
    {
        return $rootValue['name'];
    }
}

字段解析器示例

class NameResolver extends AbstractFieldResolver
{
    public function resolve($rootValue, array $arguments, $context, ResolveInfo $info): string
    {
       return $rootValue['name'];
    }
}

N+1问题

解析器函数可以返回一个值，一个promise或promise数组。以下解析器函数示例说明了如何使用promise来解决N+1问题，完整示例可以在该测试用例中找到。

$movieType = newObjectType([
    'fields' => [
        'title'    => ['type' => stringType()],
        'director' => [
            'type'    => $directorType,
            'resolve' => function ($movie, $args) {
                DirectorBuffer::add($movie['directorId']);
                
                return new Promise(function (callable $resolve, callable $reject) use ($movie) {
                    DirectorBuffer::loadBuffered();
                    $resolve(DirectorBuffer::get($movie['directorId']));
                });
            }
        ]
    ]
]);

变量

您可以在执行查询时通过将它们传递给graphql函数来传递变量。

$query = '
query HeroNameQuery($id: ID!) {
  hero(id: $id) {
    name
  }
}';

$variables = ['id' => '1000'];

$result = graphql($schema, $query, null, null, $variables);

上下文

如果您需要将一些重要的上下文信息传递到您的查询中，您可以使用graphql上的$contextValues参数来这样做。这些数据将作为$context参数传递给您的所有解析器。

$contextValues = [
    'currentlyLoggedInUser' => $currentlyLoggedInUser,
];

$result = graphql($schema, $query, null, $contextValues, $variables);

标量

模式中的叶节点称为标量，每个标量解析为某些具体数据。GraphQL中的内置或指定的标量如下

布尔值
浮点数
整数
ID
字符串

自定义标量

除了指定的标量之外，您还可以定义自己的自定义标量，并通过将其作为 buildSchema 函数的 $options 参数的一部分传递来让您的模式了解它们。

自定义日期标量类型示例

$dateType = newScalarType([
    'name'         => 'Date',
    'serialize'    => function ($value) {
        if ($value instanceof DateTime) {
            return $value->format('Y-m-d');
        }
        return null;
    },
    'parseValue'   => function ($value) {
        if (\is_string($value)){
            return new DateTime($value);
        }
        return null;
    },
    'parseLiteral' => function ($node) {
        if ($node instanceof StringValueNode) {
            return new DateTime($node->getValue());
        }
        return null;
    },
]);

$schema = buildSchema($source, [
    'Query' => QueryResolver::class,
    [
        'types' => [$dateType],
    ],
]);

每个标量都必须被强制转换，这由三个不同的函数完成。 serialize 函数将 PHP 值转换为相应的输出值。 parseValue 函数将变量输入值转换为相应的 PHP 值，而 parseLiteral 函数将 AST 文本转换为相应的 PHP 值。

高级使用

如果您正在寻找本文档尚未涵盖的内容，那么您最好的选择是查看此项目的测试。您会惊讶地发现那里有多少示例。

集成

Laravel

以下是一个示例，说明您如何在 Laravel 项目中使用此库。您需要一个应用程序服务来将此库暴露给您的应用程序，一个服务提供程序来注册该服务，一个控制器和一个路由来处理 GraphQL POST 请求。

app/GraphQL/GraphQLService.php

class GraphQLService
{
    private $schema;

    public function __construct(Schema $schema)
    {
        $this->schema = $schema;
    }

    public function executeQuery(string $query, array $variables, ?string $operationName): array
    {
        return graphql($this->schema, $query, null, null, $variables, $operationName);
    }
}

app/GraphQL/GraphQLServiceProvider.php

class GraphQLServiceProvider
{
    public function register()
    {
        $this->app->singleton(GraphQLService::class, function () {
            $schemaDef = \file_get_contents(__DIR__ . '/schema.graphqls');

            $executableSchema = buildSchema($schemaDef, [
                'Query' => QueryResolver::class,
            ]);

            return new GraphQLService($executableSchema);
        });
    }
}

app/GraphQL/GraphQLController.php

class GraphQLController extends Controller
{
    private $graphqlService;

    public function __construct(GraphQLService $graphqlService)
    {
        $this->graphqlService = $graphqlService;
    }

    public function handle(Request $request): JsonResponse
    {
        $query         = $request->get('query');
        $variables     = $request->get('variables') ?? [];
        $operationName = $request->get('operationName');

        $result = $this->graphqlService->executeQuery($query, $variables, $operationName);

        return response()->json($result);
    }
}

routes/api.php

Route::post('/graphql', 'app\GraphQL\GraphQLController@handle');

贡献者

该项目的存在归功于所有贡献者。贡献。

支持者

感谢所有支持者！ 🙏 成为支持者

赞助商

通过成为赞助商来支持此项目。您的徽标将在这里显示，并提供到您网站的链接。成为赞助商

许可证

请参阅许可协议。

digiaonline/ graphql

维护者

详细信息