README

使用 Neos 和 Flow 简单地创建 GraphQL API，请访问 https://www.neos.io/ 和 https://flow.neos.io/。

背景

此包是一组小工具，可简化使用 Neos 和 Flow 提供 GraphQL 端点。它是对 webonyx 的 PHP 版本的包装，可以自动从 PHP 代码生成模式（使用 wwwision/types）以及易于配置的 PSR-15 兼容 HTTP 中间件。

使用方法

通过 composer 安装

composer require wwwision/graphql

简单教程

创建一个包含至少一个具有 Query 属性的公共方法的类（更多详细信息请参阅 wwwision/types-graphql）

// YourApi.php
<?php
namespace Your\Package;

use Neos\Flow\Annotations as Flow;
use Wwwision\TypesGraphQL\Attributes\Query;

#[Flow\Scope('singleton')]
final class YourApi
{
    #[Query]
    public function ping(string $name): string {
        return strtoupper($name);
    }
}

现在在某个 Objects.yaml 配置中为 虚拟对象 定义 HTTP 中间件

// Objects.yaml
'Your.Package:GraphQLMiddleware':
  className: 'Wwwision\GraphQL\GraphQLMiddleware'
  scope: singleton
  factoryObjectName: Wwwision\GraphQL\GraphQLMiddlewareFactory
  arguments:
    1:
      # GraphQL URL
      value: '/graphql'
    2:
      # PHP Class with the Query/Mutation attributed methods
      value: 'Your\Package\YourApi'

最后，在 Settings.yaml 中注册该自定义中间件

// Settings.yaml
Neos:
  Flow:
    http:
      middlewares:
        'Your.Package:GraphQL':
          position: 'before routing'
          middleware: 'Your.Package:GraphQLMiddleware'

这样，一个可工作的 GraphQL API 就可以在 /graphql 下方访问。

复杂类型

默认情况下，与指定 API 类 相同命名空间 的所有类型都将自动解析，因此您可以这样做

// YourApi.php
// ...
#[Query]
public function ping(Name $name): Name {
    return strtoupper($name);
}

只要在同一命名空间（Your\Package）中存在合适的 Name 对象即可。要支持来自 不同 命名空间的类型，可以在 GraphQLMiddlewareFactory 的第三个参数中指定它们

// Objects.yaml
'Your.Package:GraphQLMiddleware':
  # ...
  arguments:
    # ...
    # Look for classes in the following namespaces when resolving types:
    3:
      value:
        - 'Your\Package\Types'
        - 'SomeOther\Package\Commands'

身份验证

通常，GraphQL 中间件是在路由中间件之前执行的。因此，Security\Context 尚未初始化。此包允许您通过模拟 MVC 请求来“模拟”初始化安全性。这是通过 GraphQLMiddlewareFactory 的第四个参数完成的

// Objects.yaml
'Your.Package:GraphQLMiddleware':
  # ...
  arguments:
    # ...
    # Simulate a request to the Neos NodeController in order to initialize the security context and trigger the default Neos backend authentication provider
    4:
      value: 'Neos\Neos\Controller\Frontend\NodeController'

重要

由于 Flow 解析此配置的方式，必须确保参数定义之间没有空格。要仅指定模拟控制器，可以将第三个参数传递为空 value: [] 数组

自定义解析器

从版本 5.2 开始，可以注册自定义函数，以动态扩展类型的操作行为

// Objects.yaml
'Your.Package:GraphQLMiddleware':
  # ...
  arguments:
    # ...
    # custom resolvers
    5:
      value:
        'User':
          'fullName':
            description: 'Custom resolver for User.fullName'
            resolverClassName: Some\Package\SomeCustomResolvers
            resolverMethodName: 'getFullName'
          'isAllowed':
            resolverClassName: Some\Package\SomeCustomResolvers

注意

如果自定义字段名与 resolverMethodName 相同，则可以省略它

重要

由于 Flow 解析此配置的方式，必须确保参数定义之间没有空格。要仅指定自定义解析，可以将第三个参数传递为空 value: [] 数组，并将第四个参数传递为 value: null

所有自定义解析器都必须是公共函数，以扩展类型作为第一个参数（以及可选的附加参数），并指定返回类型。

例如，上面的解析器类可能如下所示：

final class SomeCustomResolvers {

    public function __construct(private readonly SomeDependency $incjection) {}
    
    public function getFullName(User $user): string {
        return $user->givenName . ' ' . $user->familyName;
    }
    
    public function isAllowed(User $user, Privilege $privilege): bool {
        return $this->incjection->isUserPrivilegeAllowed($user->id, $privilege);
    }
}

更多

有关更多示例和如何使用更复杂类型的说明，请参阅wwwision/types和wwwision/types-graphql。

常见问题解答（FAQ）

 use Doctrine\ORM\Mapping as ORM;
 use Neos\Flow\Annotations as Flow;

 /**
  * @ORM\Entity
  * @Flow\Proxy(false)
  */
class TestEntity
{

    /**
     * @var string
     * @ORM\Id
     */
    public readonly string $id;

    /**
     * @var string
     * @ORM\Column(length=80)
     */
    public readonly string $title;

    public function __construct(string $id, string $title) {
        $this->id = $id;
        $this->title = $title;
    }
}

贡献

以 问题 或 拉取请求 形式做出的贡献非常受欢迎

许可协议

请参阅 LICENSE