README

API 的观点微框架

安装

运行

$ composer require refinery29/piston

基本应用程序

这是您能编写的最简单的 Piston 应用程序。首先实例化一个新的 Piston 对象，然后使用 addRoute() 方法向该对象添加路由。此方法需要三个参数

• 路由方法：可以是单个方法，也可以是支持的方法数组
• 路由：包含静态或参数化路由的字符串
• 处理器：需要接受请求和响应对象

以下示例中，我们使用匿名函数作为处理器添加默认路由。

require_once 'vendor/autoload.php';

use Refinery29\Piston\ApiResponse as Response;
use Refinery29\Piston\Piston;
use Refinery29\Piston\Request;

$application = new Piston();
$application->addRoute(
  'GET', '/',
  function(Request $request, Response $response) {
    return $response;
  }
);

$application->launch();

设置好路由后，调用 launch() 方法。这会尝试渲染进程管道并分配客户端请求，从而向客户端发出响应。它不会做任何事情特殊，只是返回一个 JSON 响应，如果渲染在浏览器中，看起来如下所示

路由

Piston 支持基于类的路由。被路由到的类必须返回 Refinery29\Piston\Http\Request 的一个实例。路由实现为简单的值对象，包含 4 个属性。这些是：一个 URL 别名，一个 HTTP 动词，以及一个 动作。以下是一个此类的基本实现。

<?php
namespace Refinery29\DummyPistonApp\Controller;

use Refinery29\Piston\Request;
use Refinery29\Piston\ApiResponse as Response;

class JediController
{
    public function renderHomePage(Request $request, Response $response)
    {
        return $response;
    }
}

以下是对之前示例的修订，使用该控制器类作为路由的处理器。

require_once 'vendor/autoload.php';

use DummyPistonApp\Controller;
use Refinery29\Piston\Piston;

$application = new Piston();
$application->addRoute('GET', '/', Controller\JediController::class . '::renderHomePage');

$application->launch();

参数化路由

league/route 允许使用参数化路由，例如 /jedi/master/{name}。您可以强制参数是数字或单词：{id:number}/{name:word}。

路由组

您还可以创建可以捆绑某些路由的路由组。如果您想构建一系列关于绝地的路由，以 /jedi 前缀的路由，则路由组是最佳选择。

// include the RouteGroup class
use Refinery29\Piston\Router\RouteGroup;

$routeGroup = $application->group('/jedi', function (RouteGroup $group) {
    $group->get('/masters', Controller\JediController::class . '::getJediMasters');
    $group->get('/padawans’, Controller\JediController::class . '::getJediPadawans');
});

路由组还接受一个 URL 段作为第二个参数

$group = new RouteGroup([], 'admin');

此组中的所有路由都将具有前面添加的此 URL 段的 URL，结果为 admin/route_url。有关更详细的信息，请参阅文档中的路由组部分。

管道（中间件）

Piston 提供了在应用程序执行过程中可以连接以添加功能的不同位置。这允许您在启动应用程序时在不同点采取行动。

管道存在于两个级别

• 应用程序/全局级别
• 路由组级别

钩子按从最不具体（应用程序）到最具体（路由组）的顺序应用。钩子必须实现 League\Pipeline\StageInterface 并定义一个 process() 方法，该方法必须返回 Refinery29\Piston\Http\Request 的一个实例，如下例所示。

$hook = new UseTheForceHook();
$application->addMiddleware($hook);

有关更详细的信息，请参阅文档中的管道部分。

装饰器

Piston 允许自己被装饰以添加功能。

装饰器必须实现 Refinery29\Piston\Decorator 接口并定义一个 register() 函数。该 register() 函数必须返回 'Refinery29\Piston\Piston` 的一个实例。

服务提供者

服务提供商可以轻松添加，以封装应用所需的任何服务。任何服务提供商类都必须实现League\Container\ServiceProvider

$application = new Piston();
$application->register(new LightSaberProvider());

查询参数

Piston是一个专注于API的框架，因此封装了多种不同的查询参数选项。

#### 字段

可以请求应用中的特定字段，目的是仅返回这些字段。字段指定为逗号分隔的列表。

url.com?fields=jedi,sith,yoda

上述URL将被自动解析，您可以通过以下方式检索该信息

$request->getRequestedFields();

您可以确定请求是否请求了字段：$request->hasRequestedFields()

分页

Piston目前仅支持基于游标的分页。

url.com?before=124ksl&after=0809asdj这些参数在请求中如下所示

$request->getPaginationCursor()

此函数返回一个包含键before和after的数组

您可以确定请求是否分页：$request->isPaginated()

包含的资源

您还可以请求在响应中包含不同的关系。

url.com?include=master,padawan,planet

这些参数将可用：$request->getIncludedResources()，它将返回请求的关系数组。

嵌套关系

您还可以请求嵌套资源。

url.com?include=jedi.master.padawan,planet

这些参数的访问方式与单级关系相同，但是结果不同

array
	[0] => array
   				[0] => jedi
   				[1] => master
   				[2] => padawan
   	[1] => planet

排序

排序参数作为请求中的sort查询参数提供

url.com?sort=-created,title

排序查询参数应该是排序属性的逗号分隔列表。

排序顺序通过使用减号作为排序属性前缀的否定来定义（例如，-created被否定，而created没有被否定）。如果排序属性被否定，则排序方向为'DESC'（降序），否则使用'ASC'（升序）。

可以通过调用Request#getSort($name)来检查排序值，它将返回'ASC'或'DESC'。

上述所有过滤器仅允许在GET请求上使用。如果与任何其他HTTP动词一起使用，则使用任何这些参数都将导致错误。

行为准则

请参阅CONDUCT.md。