README

Flight 微型框架捆绑了 Swagger、PHPUnit 和其他有用工具。旨在通过包含基本项目设置、测试路由和模型以及单元测试模板，帮助快速启动使用上述工具构建的API的开发。

入门

先决条件

本指南假设您正在使用（或计划使用）以下技术在您的项目中

• PHP 7.1+
• Composer
• Xdebug（如果您计划使用PHPUnit，则必需）

安装

1. 首先，请确保您已安装并配置了一个运行中的Web服务器（例如Apache），并使用PHP 7.1或更高版本。

2. 使用 composer 下载项目骨架，安装所有必需的依赖项，并运行示例单元测试

   composer create-project tribeos/flight-php-swagger path/to/project

启用URL重写

由于Flight依赖于Apache 2的mod_rewrite模块以正常工作，因此您应该首先通过a2enmod启用它，然后重新启动服务器

sudo a2enmod rewrite

sudo systemctl restart apache2

之后，您还应编辑Apache的默认配置文件，因为其最初禁止使用.htaccess文件来应用重写规则。该配置文件通常位于/etc/apache2/apache2.conf。在其中，找到有关/var/www目录的块，并确保AllowOverride设置为All，并且设置了Require all granted。

<Directory /var/www/>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
</Directory>

保存更改后，重新启动Apache服务器。

如果您有多个网站配置，或者想要有多个网站配置，您还可以通过编辑/etc/apache2/sites-available中的所需配置文件，为每个网站单独启用重写规则。有关更多信息，请参阅以下教程。

注意：上述说明假设您正在使用Ubuntu发行版。如果您使用的是其他操作系统，请参阅启用重写模块的相关教程。

• Windows (WAMP/XAMPP)
• CentOS

安装缺少的PHP扩展

项目和其依赖项需要安装某些PHP扩展。您可能缺少的常见扩展可能包括以下一些

注意：与之前的Apache 2部分一样，这些说明适用于Ubuntu发行版。如果您使用的是其他操作系统，请参阅适当的替代命令。

项目结构

安装完成后，您将在项目中找到以下结构

path/to/project
├── app 
│   ├── models
│   │   └── SampleModel.php
│   ├── routes
│   │   ├── FlightSetup.php
│   │   └── SampleRoute.php
│   └── utils
│       └── Validator.php
├── config
│   ├── config.php
│   └── config.sample.php
├── docs
├── logs
│   └──  .htaccess
├── tests
│   ├── build
│   └── unit
│       └── SampleTest.php
├── vendor
├── .gitignore
├── .htaccess
├── autoload.php
├── composer.json
├── composer.lock
├── index.php
├── LICENSE
├── phpunit.xml
└── README.md

主要项目组件概述

• app：主应用程序文件夹
  • models：用于请求/响应的模型
  • routes：API路由的定义
  • utils：应用程序实用工具，例如验证器和记录器
• config：配置文件
• docs：Swagger文档文件
• logs：日志存储
• tests：应用测试文件夹
  • build：由测试生成的任何编译文件（代码覆盖率等）
  • src：测试源文件
• vendor：所有库和第三方代码的位置
• autoload.php：一个引导文件，用于加载Composer依赖项，并包含所有其他项目文件
• index.php：API入口点
• phpunit.xml：PHPUnit测试配置

项目开发

项目配置

所有与项目（以及Swagger文档）相关的配置都在config/config.php文件中处理。根据您的项目需求更改/添加配置常量。

另一个重要的文件是index.php，它作为API入口点。它需要包含加载Composer依赖项的代码以及所有其他必要项目文件的autoload.php文件。此外，它启动Flight框架。默认导入的文件包括所有models、routes和utils文件，以及项目配置文件（config/config.php）、Swagger-PHP配置文件（docs/swagger.php）和Composer的vendor/autoload.php。根据您的项目需求更改/添加导入的文件。

Flight

Flight是一个可扩展且易于使用的PHP框架，它允许快速创建RESTful Web API。它使您可以创建详细的、功能性的API端点，并配合中间件功能以及覆盖/创建自定义方法的能力。

Flight::route('GET /sample/@value', function($value) {
    Flight::json([ 'sample_value' => $value ]);
});

项目中的所有路由都通过Flight完成。初始Flight设置（FlightSetup.php）以及所有项目路由都在routes文件夹中处理，可以根据您的需求进行更改。

关于Flight的详细使用文档和示例可以在Flight主页 - "学习"区域找到。有关Flight框架本身的更多详细信息，您可以访问其GitHub仓库。

Swagger-PHP

在routes文件夹中创建路由后，您可以开始编写和生成您的RESTful API的OpenAPI文档。

文档在对应的路由之上，使用PHP注释块（即DocBlocks）编写。

/** 
 * @OA\Get(
 *      path="/sample/route",
 *      tags={"sample"},
 *      summary="A sample route.",
 *      @OA\Response(
 *           response=200,
 *           description="A sample response."
 *      ),
 *     security={
 *          {"api_key": {}}
 *      }
 * )
*/

您可以定义每个RESTful端点的路径、标签、简短摘要、参数、默认参数值、请求体、可用的响应、安全认证以及其他许多选项。

一般Swagger配置，如项目名称、项目作者、API服务器URL、规范文件夹等，可以在config/config.php中的"Swagger配置常量"区域找到并配置。

项目骨架附带docs文件夹，其中包含Swagger文档所需的所有文件（PHP设置文件、HTML和CSS）。文档可以通过在浏览器中导航到项目的根路由（/）来访问。

有关Swagger的一般信息和OpenAPI标准，请参阅Swagger官方网站。有关PHP实现的详细使用文档和示例，请参阅swagger-php官方网站。

项目实用工具

日志记录器

项目附带http-logger，它是一个HTTP请求、响应和错误日志记录器，默认情况下将每个传入请求及其相应的响应记录到logs/debug.log中，以制表符分隔值（TSV）的形式。详细的日志记录信息配置细节可以在其GitHub页面找到。

日志记录器需要日志文件的位置（默认情况下，它通过 config/config.php 中的常量配置）。此外，为了充分利用日志记录器的功能，应该禁用 Flight 的内部错误处理器（如果已启用，它将在 http-logger 之前捕获某些类型的错误）。

/* Disbale FlightPHP's internal error logger. */
Flight::set('flight.handle_errors', false);
HttpLogger::create('file', 'full+h', LOG_FILE, false);

/* Get and use the logger */
$logger = HttpLogger::get();
$logger->log();

日志记录器通过 routes/FlightSetup.php 包含，并在 Flight 中间件函数 Flight::after() 中配置，该函数在每次请求后运行（因此它能够获取适当的响应）。您可以根据需要更改日志记录器的功能以及它将监视的路线。

Flight::output()

Flight::output() 是一个自定义映射的方法，它结合了 Flight::json()（JSON 响应输出）和自定义 HTTP 日志记录器的功能。通过此方法发送的任何 API 响应都将自动根据日志记录器中设置的偏好进行记录。该方法在 routes/FlightSetup.php 中定义和配置。

当您想在请求/响应对中使用日志记录功能而不使用 Flight 中间件拦截时，这很有用。

Flight::output() 接受两个参数：要发送的实际数据（必需）和响应代码（可选，默认为 200）。

Flight::output(['sample_message' => 'Sample response.'], 301);

Flight::validate()

Flight::validate() 使用 Swagger-PHP 分析来确定传入的请求体是否有效（包含所有必需的属性），这是根据预期的 OpenAPI 模型规范进行的。

所有模型都声明为类，并且它们的属性设置为公共。这些模型在 app/models 中定义，并遵循以下结构

/**
 * @OA\Schema(
 * )
 */
class SampleModel {
    /**
     * @OA\Property(
     * description="Sample attribute of the request body.",
     * example="Sample string."
     * required=true
     * )
     * @var string
     */
    public $sample_attribute;
}

在这个具体示例中，description 用于给出模型属性的简要概述，required 决定该属性是否为必需，example 为其分配默认值。有关模型模式的信息，请参阅 Swagger-PHP 文档。

模型验证类在 utils/Validator.php 中声明和定义，并在 routes/FlightSetup.php 中作为自定义映射的 Flight 方法包含。它接受两个参数：用于验证请求体的类本身和请求体。

Flight::validate(SampleModel::class, Flight::request()->data->getData());

该方法应在 API 路由内部调用，在调用任何其他方法之前。如果模型有效，则请求将继续执行。如果模型验证失败，它将输出 400 Bad Request 响应代码，终止请求。

注意：Flight::validate() 依赖于 Flight::output()，因此如果您计划从项目中删除自定义输出方法，则应按要求重写验证映射方法。

项目测试

该项目包含 PHPUnit，这是一个 PHP 测试框架，它不仅可以进行自我测试，还可以生成代码覆盖率。

测试设置

与 PHPUnit 相关的所有设置都位于 phpunit.xml 中。有几种设置选项可用

1. 测试文件的位置在 testsuites 标签内，可以定义将要扫描测试的位置。默认情况下，这是 tests/unit。当定义测试目录（通过 directory 标签）时，测试文件将在测试执行期间按字母顺序运行。如果需要，我们还可以通过 file 标签定义测试文件的顺序。

    <testsuites>
        <testsuite name="sample-test-suite">
            <directory suffix="Test.php">tests/src/</directory>
            <!-- By default, test files will be run in alphabetical file order. If you want to set a specific order of execution, define individual test files-->
            <!-- <file>tests/src/SampleTest.php</file> -->
        </testsuite>
    </testsuites>

1. 测试覆盖报告类型在测试运行之后可以生成不同类型的测试报告。日志类型在 logging 标签中定义。所有编译后的测试文件默认情况下位于 tests/build 内。

    <logging>
        <!-- Types of testing logs -->
        <log type="testdox-html" target="tests/build/testdox.html"/>
        <log type="tap" target="tests/build/report.tap"/>
        <log type="junit" target="tests/build/report.junit.xml"/>
        <log type="coverage-html" target="tests/build/coverage"/>
        <log type="coverage-text" target="tests/build/coverage.txt"/>
        <log type="coverage-clover" target="tests/build/logs/clover.xml"/>
    </logging>

1. 要包含/排除的文件 从代码覆盖率中包含或排除的文件，您还可以选择哪些文件将包含（或排除）在代码覆盖率报告中。这通过在 whitelist 标签内部使用 filter 标签来完成。默认情况下，项目的PHPUnit设置会覆盖 app 目录下的文件，排除 models 和 routes（因为这些文件夹不包含可以进行有效代码覆盖率测试的代码）。您还可以定义自己的自定义包含/排除文件夹和文件。

    <filter>
        <whitelist>
            <!-- The name of the folder to use for code coverage -->
            <directory suffix=".php">app/</directory>
            <exclude>
                <!-- Files/folders excluded from code coverage (PHP files without testable methods). Edit according to your project needs. -->
                <directory suffix=".php">app/models</directory>
                <directory suffix=".php">app/routes</directory>
            </exclude>
        </whitelist>
    </filter>

编写测试

所有单元测试默认应编写在 tests/unit 目录中。测试文件名应以 Test.php 结尾，以便由PHPUnit（如 phpunit.xml 中定义）发现，例如 SampleTest.php。

测试类定义为扩展 TestCase 类，并可以包含各种测试方法。在命名测试时，您可以使用以下约定：test + 测试描述（驼峰式命名，例如 testThisIsASampleTest）。这将允许在测试执行期间将测试用例名称转换为描述性句子，为开发者提供有关测试应做什么的额外概述。

/* tests/unit/SampleTest.php */

<?php
use PHPUnit\Framework\TestCase;

class SampleTest extends TestCase {

    public function testThisIsASampleTest() {
        $this->assertTrue(true);
    }
}

测试执行

要执行所有测试，请在项目的根目录中运行 vendor/bin/phpunit --testdox。

root@ubuntu:/path/to/project$ vendor/bin/phpunit --testdox
PHPUnit 7.5.16 by Sebastian Bergmann and contributors.

Sample
 ✔ This is a sample test

要运行单个测试文件，请提供其路径：vendor/bin/phpunit --testdox tests/unit/SampleTest.php

--testdox 标志是可选的，但建议使用，因为它将根据测试名称生成描述性句子（如上文所述），使理解测试内容更容易。

执行测试后，代码覆盖率报告将在 tests/build/coverage 目录中生成，可以通过浏览器打开此路径进行查看。

作者

• Aldin Kovačević，对骨架和文档的初始工作 - Aldin-SXR

许可证

该骨架遵循 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

正在进行中。