README

简介

项目理念是简洁和高质量的代码。

与大多数（目前所有）实现不同，如 webonyx、youshido 或 digitalonline，Railt 包含了一个完全基于自己实现的 GraphQL SDL 解析器，该解析器基于 EBNF 类语法。这种机会不仅允许我们拥有语言的原始实现并始终保持最新，而且还可以实现新的向后兼容功能，这些功能其他实现无法提供。

Railt 的目标

不要重复基于 JS 的实现中犯下的错误。
为 PHP 开发者实现一个现代化和便捷的环境。
实现基于 PSR 的任何现成解决方案的简单集成。
提供熟悉的功能（包括依赖注入、路由等）。

安装

composer require railt/railt

快速入门

本教程有助于您

获得对 GraphQL 原则的基本理解。
定义一个表示您的数据集结构的 GraphQL 模式。
运行一个 Railt 应用程序实例，允许您针对您的模式执行查询。

本教程假定您熟悉命令行、PHP，并已安装最新版本的 PHP（v8.1+）。

第 1 步：创建新项目

从您首选的开发目录中，为新项目创建一个目录并将 cd 进入它

mkdir railt-example
cd railt-example

使用 Composer 初始化新项目

composer init
composer require railt/railt dev-master@dev

您的项目目录现在包含一个 composer.json 文件。

请注意，如果出现与安装开发版本相关的安装错误（"根据您的最低稳定性设置，该包不可用足够稳定的版本"），您需要将 "minimum-stability": "dev" 指定在 composer.json 文件中。

更多信息请参阅 https://getcomposer.org.cn/doc/04-schema.md#minimum-stability

运行 Railt 应用程序的应用程序可能需要两个顶级依赖项

railt/webonyx-executor - 一个提供 webonyx/graphql-php 桥接以启动和处理 GraphQL 请求的执行器。
railt/router-extension - 一个路由扩展，它提供了一种方便的方法将 GraphQL 请求委托给控制器实例。

或者，您可以选择分别安装所有组件
composer require railt/factory railt/webonyx-executor railt/router-extension

第 2 步：定义您的 GraphQL 模式

每个 GraphQL 应用程序（包括 Railt）都使用模式来定义客户端可以查询的数据结构。在本例中，我们将创建一个用于按 id 和 name 查询用户集合的应用程序。

在您的首选代码编辑器中打开 index.graphqls 并将以下内容粘贴到其中

# Comments in GraphQL strings (such as this one)
# start with the hash (#) symbol.

# This "User" type defines the queryable fields for
# every user in our data source.
type User {
    id: ID
    name: String
}

# The "Query" type is special: it lists all of the
# available queries that clients can execute, along with
# the return type for each. In this case, the "books"
# query returns an array of zero or more Books (defined above).
type Query {
    users: [User]
}

现在只需打开（创建）index.php 文件并将以下内容粘贴到其中

<?php

require __DIR__ . '/vendor/autoload.php';

//
// Create An Application
//
$application = new Railt\Foundation\Application(
    executor: new Railt\Executor\Webonyx\WebonyxExecutor(),
);

$application->extend(new Railt\Extension\Router\DispatcherExtension());

//
// Creating a connection instance that will process
// incoming requests and return responses.
//
$connection = $application->connect(
    schema: new \SplFileInfo(__DIR__ . '/index.graphqls'),
);

此片段定义了一个简单、有效的 GraphQL 模式。客户端将能够执行名为 users 的查询，我们的服务器将返回零个或多个 User 数组。

第 2.1 步：模式健康检查

要对应用程序进行健康检查，您可以手动创建一个GraphQLRequest实例，通过传递包含所需GraphQL查询字符串的请求对象。

//
// Passing a request to the specified connection.
// 
$response = $connection->handle(
    request: new \Railt\Http\GraphQLRequest(
        query: '{ users { id, name } }',
    ),
);

dump($response->toArray());

//
// Expected Output:
//
// array:1 [
//   "data" => array:1 [
//     "users" => []
//   ]
// ]
//

步骤 3：定义控制器

解析器告诉Railt应用程序如何获取与特定类型关联的数据。由于我们的User数组是硬编码的，因此相应的解析器很简单。

创建一个名为UserController的控制器文件，例如，包含一个index()方法以及以下代码

<?php

class UserController
{
    public function index(): iterable
    {
        return [
            ['id' => 1, 'name' => 'Vasya'],
            ['id' => 2, 'name' => 'Petya'],
        ];
    }
}

确保该类可用于自动加载，或者该文件包含在index.php中。

步骤 4：将字段绑定到控制器操作

我们已经定义了数据集，但Railt应用程序不知道在执行查询时应使用该数据集。为了解决这个问题，我们创建一个路由。

路由告诉Railt如何获取与特定类型关联的数据。由于我们的User数组是硬编码的，因此相应的路由很简单。

将以下@route指令添加到index.graphqls文件的底部

# ...
type User {
    id: ID
    name: String
}

# ...
type Query {
    users: [User]
        # Route directive can be defined here
        @route(action: "UserController->index")
}

步骤 5：处理HTTP

为了传递请求数据并发送响应，我们必须完成我们的index.php文件。

{提示}如果您使用Symfony、Laravel或其他http层（例如，psr-7），则可以根据提供的框架API和/或规范组织数据获取。

$data = json_decode(file_get_contents('php://input'), true);

$response = $connection->handle(
    request: new \Railt\Http\GraphQLRequest(
        query: $data['query'] ?? '',
        variables: $data['variables'] ?? [],
        operationName: $data['operationName'] ?? null,
    ),
);

$json = json_encode($response->toArray());

header('Content-Type: application/json');
header('Access-Control-Allow-Origin: *');

echo $json;

步骤 6：启动服务器

我们现在可以启动我们的服务器了！从您项目的根目录运行以下命令

php -S 127.0.0.0:80

您应该在终端底部看到以下输出

PHP 8.2.6 Development Server (http://127.0.0.1:80) started

我们已启动！

步骤 7：执行第一个查询

我们可以在服务器上执行GraphQL查询。要执行第一个查询，我们可以使用Apollo Sandbox、GraphQL Playground或其他工具。

我们的服务器支持一个名为users的单一查询。让我们执行它！

这是执行users查询的GraphQL查询字符串

{
  users {
    id
    name
  }
}

将此字符串粘贴到查询面板中，然后单击“发送请求”按钮（GraphQL界面和面板布局可能取决于您使用的平台/客户端）。结果（来自我们的硬编码数据集）将出现在响应面板中

GraphQL最重要的概念之一是客户端可以选择只查询他们需要的字段。从查询字符串中删除name并再次执行它。响应更新，只包括每个User的id字段！

学习Railt

完整文档可在官方网站上找到。

贡献

感谢您考虑为Railt框架做出贡献！贡献指南可在文档中找到。

安全漏洞

如果您在Railt中发现安全漏洞，请发送电子邮件至nesk@xakep.ru。所有安全漏洞都将得到及时处理。

许可

Railt框架是开源软件，根据MIT许可证授权。

帮助 & 社区

如果在运行过程中遇到问题或有疑问，请加入我们的Discord社区。我们喜欢与您交流！

railt / railt

维护者

详细信息