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(),
    ],
]);

解析器中间件

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

中间件之前示例

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

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

中间件之后示例

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

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

贡献者

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

赞助商

感谢所有赞助商！🙏 成为赞助商

赞助商

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

许可证

见许可证。

hsd-tech / graphql

维护者

详细信息