README

PSX 是一个创新的 PHP 框架，专门用于构建完全类型的 REST API。

它通过提供以下功能来帮助提高 API 开发过程：

• 完全类型化的控制器类
• 客户端 SDK 生成器
• OpenAPI 生成器
• 根据 TypeSchema 规范生成模型类
• 使用 Symfony DI 容器 组件
• 与 Doctrine DBAL 和 migrations 一起工作
• 类型安全的数据库交互
• 端点集成测试

有关 PSX 的更多信息，请访问 phpsx.org。

安装

要安装此框架，您可以简单地安装此演示 API 项目。

composer create-project psx/psx .

入门

此存储库已包含一个完全工作的演示 API，该 API 使用 PSX 构建，您可以使用它作为起点，并更好地了解 PSX 的工作方式。以下我们将基于演示文件介绍 PSX 的重要概念。

控制器

控制器是您的应用程序的入口点，由框架调用。控制器是一个简单的 PHP 类，包含属性以使特定方法可调用。以下示例中有一个简单的控制器，其中包含 getAll 和 create 方法，当 GET 或 POST 请求到达 /population 端点时会被调用。

class Population extends ControllerAbstract
{
    #[Get]
    #[Path('/population')]
    public function getAll(#[Query] ?int $startIndex = null, #[Query] ?int $count = null): Model\PopulationCollection
    {
        return $this->populationTable->getCollection($startIndex, $count);
    }

    #[Post]
    #[Path('/population')]
    public function create(#[Body] Model\Population $payload): Model\Message
    {
        $id = $this->populationService->create($payload);

        $message = new Model\Message();
        $message->setSuccess(true);
        $message->setMessage('Population record successfully created');
        $message->setId($id);
        return $message;
    }
}

PSX 的一个关键概念是，您的公开控制器方法的参数与传入 HTTP 请求的值映射。在 getAll 方法中，$startIndex 和 $count 参数映射到 HTTP 请求的查询参数，在 create 方法中，$payload 参数映射到请求体。如果您熟悉 Spring 或 NestJS，您已经知道这种方法。

PSX 使用 symfony DI 容器，所有控制器类都通过自动装配自动加载。这意味着您可以在构造函数中简单地定义控制器所需的所有依赖项。如果您想自定义加载哪些类，请参阅 container.php。

SDK

PSX 最伟大的功能之一是它可以自动为构建的 API 生成客户端 SDK。要生成客户端 SDK，请运行以下命令。

php bin/psx generate:sdk

这会将 SDK 写入 output/ 文件夹。默认情况下，该命令生成 TypeScript SDK。基于上面定义的控制器，PSX 会生成以下客户端 SDK。

const client = new Client(...);

client.population().getAll(startIndex?: number, count?: number);
client.population().create(payload: Population);

客户端包含与后端定义相同的模式，但已转换为 TypeScript。这意味着您在前后端使用的是完全相同的模式。如果您更改后端的模式，您可以重新生成 SDK，并直接看到您新模式的所有问题。在这方面，PSX 提供了类似 tRPC 的功能，但以语言无关的方式。

generate:sdk 命令接受一个参数，该参数定义了生成的 SDK 类型。以下列表显示了一些支持的格式。

• client-php
• client-typescript
• spec-openapi

模型

为了启用 SDK 生成，PSX 需要理解传入或传出 JSON 负载的结构。这是通过为每个参数和返回类型使用 DTO 模型来完成的。PSX 包含一个模型生成器，允许您根据 TypeSchema 规范生成这些模型。请查看包含我们演示 API 模型的 typeschema.json 文件。您可以使用以下命令生成所有模型。

php bin/psx generate:model

该命令将所有模型写入 src/Model 文件夹。然后您可以在控制器类中使用这些模型。

服务

PSX 建议将实际的业务逻辑移动到单独的服务类中。控制器随后只需调用服务的方法。虽然这不是强制性的，但它可以提高您的代码质量，因为您还可以轻松地在另一个上下文中使用此服务。所有位于 service/ 文件夹下的类都会自动加载，因此您可以通过简单的构造函数注入指定所有依赖项。

迁移

PSX 使用 doctrine migrations 来帮助管理您的数据库模式。要生成新的迁移，您可以简单地运行 s。

php bin/psx migrations:generate

这将创建一个位于 src/Migrations 的新迁移文件。然后您可以在该迁移文件中建模您的表模式。在此之后，您可以通过运行 migrate 命令来执行所有必需的数据库更改。

php bin/psx migrations:migrate

请参阅 doctrine migrations 项目以获取有关迁移系统如何工作的更多信息。

表

PSX 提供了一个命令，该命令生成表和行类，以便以类型安全的方式与数据库交互。应在执行所有迁移后执行此命令。

php bin/psx generate:table

该命令然后将所有文件写入 src/Table 文件夹。

请注意，总的来说，我们认为在 API 开发中不需要 ORM，但可以轻松地将任何现有 ORM 集成到 PSX 中。

测试

PSX 提供了一种简单地为每个控制器端点构建集成测试的方法。以下摘录显示了请求 /population 端点的测试，它简单地比较 JSON 负载与现有的 JSON 结构。

public function testGetAll(): void
{
    $response = $this->sendRequest('/population', 'GET');

    $actual = (string) $response->getBody();
    $expect = file_get_contents(__DIR__ . '/resources/collection.json');

    $this->assertEquals(200, $response->getStatusCode(), $actual);
    $this->assertJsonStringEqualsJsonString($expect, $actual, $actual);
}

通过这种方式，您可以轻松地为每个端点构建集成测试。请查看 tests/Controller/PopulationTest.php 文件以查看完整的测试用例。

组件

除了框架之外，PSX 还基于各种 PHP 组件构建。这些组件独立于框架，也可以在另一个上下文中使用。以下列表包含了一些最显著的包

• psx/api
  解析和生成 API 规范格式
• psx/schema
  解析和生成数据模式格式
• psx/data
  数据处理库，用于以不同格式读取和写入 POPO
• psx/sql
  从您的数据库生成类型安全的 PHP 类