README

Route 会自动将 CRUD 映射到定义模块中的 Presenters 和动作。并在 Presenter 中创建可访问的参数。

格式
id（自动检测）
关联（关联数组）
data（请求中的原始数据）
query（查询字符串中的项数组）

格式检测

变量 $format 从 HTTP 头 Accept 中检测。如果头不存在，Route 会尝试从 URL（例如 .../foo.json）中检测格式。如果 URL 中没有格式，Route 会使用默认格式 json。

安装

安装 Nette-RestRoute 的最佳方式是使用 Composer

$ composer require adamstipak/nette-rest-route

用法

use AdamStipak\RestRoute;

// $router is an instance of Nette\Application\Routers\RouteList  

// No parameters needed. Presenter name will be generated.
$router[] = new RestRoute;

// With module.
$router[] = new RestRoute('Api');

// With module and xml as a default format.
$router[] = new RestRoute('Api', 'xml');

// With URL module versioning
$router[] = (new RestRoute())
    ->useURLModuleVersioning(
        '/v[0-9\.]+/',     // Regex for URL version
        [                  // URL fragment to module mapping
          NULL => 'V1',    // Default version module is V1
          'v1' => 'V1',    // /v1 to module V1
          'v2' => 'V2'     // /v2 to module V2
        ]
    );

第一个参数是要发送请求的模块的名称。将生成 URL 前缀。见示例。#### 示例

NULL      => /<generated presenter name>
'Api'     => /api/<generated presenter name>
'My:Api'  => /my/api/<generated presenter name>
...

第二个参数是默认格式。默认情况下，默认格式是 json。RestRoute 仅支持两种格式

json （默认）
xml

示例

读取所有

URL: /api/users → \ApiModule\UsersPresenter::actionReadAll
HTTP 头 Accept: application/json
方法: GET
请求体: 空的
参数

format = json
associations = array(0)
data = ""
query = array(0)

标志 readAll 被丢弃，并且如果没有在 URL 中找到资源 ID，Route 会自动生成动作 readAll。

使用资源 ID 读取

URL: /api/users/123 → \ApiModule\UsersPresenter::actionRead
HTTP 头 Accept: application/json
方法: GET
请求体: 空的
参数

format = json
id = 123
associations = array(0)
data = ""
query = array(0)

查询参数

URL: /api/users?foo=bar&page=1 → \ApiModule\UsersPresenter::actionReadAll
HTTP 头 Accept: application/json
方法: GET
请求体: 空的
参数

format = json
associations = array(0)
data = ""
query = array(
	foo => "bar"
	page => 1
)

创建

URL: /api/users → \ApiModule\UsersPresenter::actionCreate
HTTP 头 Accept: application/json
方法: POST
请求体

{
	"foo": "bar",
	"nested": {
		"foo": "bar"	
	}
}

参数

format = json
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)

更新

URL: /api/users/123 → \ApiModule\UsersPresenter::actionUpdate
HTTP 头 Accept: application/json
方法: PUT
请求体

{
	"foo": "bar",
	"nested": {
		"foo": "bar"	
	}
}

参数

format = json
id = 123
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)

部分更新

URL: /api/users/123 → \ApiModule\UsersPresenter::actionPartialUpdate
HTTP 头 Accept: application/json
方法: PATCH
请求体

{
	"foo": "bar",
	"nested": {
		"foo": "bar"	
	}
}

参数

format = json
id = 123
associations = array(0)
data = {"foo": "bar", "nested": {"foo": "bar"}}
query = array(0)

删除

URL: /api/users/123 → \ApiModule\UsersPresenter::actionDelete
HTTP 头 Accept: application/json
方法: DELETE
请求体: 空的
参数

format = json
id = 123
associations = array(0)
data = ""
query = array(0)

选项

有关 OPTIONS 文档的更多信息，请参阅 w3.org。

URL: /api/users → \ApiModule\UsersPresenter::actionOptions
HTTP 头 Accept: application/json
方法: OPTIONS
请求体: 空的
参数

format = json
associations = array(0)
data = ""
query = array(0)

关联

点号前的最后一个项（对）是主资源。点号之前的一切都是关联（apigee.com）。

URL: /api/users/1/comments → \ApiModule\CommentsPresenter::actionReadAll|actionCreate|actionUpdate|actionDelete
HTTP 头 Accept: application/json
方法: GET, POST, PUT, DELETE
请求体: 空的
参数

format = json
associations = array(
	users => 1
)
data = ""
query = array(0)

URL: /api/users/123/comments/456 → \ApiModule\CommentsPresenter::actionRead|actionCreate|actionUpdate|actionDelete
HTTP 头 Accept: application/json
方法: GET, POST, PUT, DELETE
请求体: 空的
参数

format = json
id = 456
associations = array(
	users => 123
)
data = ""
query = array(0)

URL: /api/users/1/blogs/2/comments → \ApiModule\CommentsPresenter::actionReadAll|actionCreate|actionUpdate|actionDelete
HTTP 头 Accept: application/json
方法: GET, POST, PUT, DELETE
请求体: 空的
参数

format = json
id = 1
associations = array(
	users => 1
	blogs => 2
)
data = ""
query = array(0)

URL 版本控制

RestRoute 提供了在 URL 中对 API 进行版本控制的选项。每个版本在您的应用程序中由单独的模块表示。

首先，您定义一个正则表达式，用于检测 URL 中是否存在版本参数。它必须在路径的开头。然后，您定义版本到模块的映射。NULL 键表示默认模块，如果未检测到版本参数。

$router[] = (new RestRoute('Api')) // Optional module
    ->useURLModuleVersioning(
        RestRoute::MODULE_VERSION_PATH_PREFIX_PATTERN,     // Regex for URL version
        [                  // URL fragment to module mapping
          NULL => 'V1',    // Default version module is V1
          'v1' => 'V1',    // /v1 to module V1
          'v2' => 'V2'     // /v2 to module V2
        ]
    );

RestRoute 现在将请求映射到 Presenters，如下所示（URL -> Presenter）

/api/foo        ->  Api:V1:Foo
/api/v1/foo     ->  Api:V1:Foo
/api/v2/foo     ->  Api:V2:Foo

文件上传

RestRoute 读取标准的 PHP 输入，并将数据放入操作中的 $data 参数。这适合单个文件上传或分块上传，因为它包含原始数据。

对于多个文件上传，RestRoute 在创建时只需设置文件 \Nette\Application\Request。在演示者中，注入 \Nette\Application\Request 服务并使用这些文件。

class FooPresenter {
  /** @var \Nette\Application\Request @inject */
  public $request;

  public function actionCreate () {
    $files = $this->request->getFiles();
  }
}

开发

RestRoute 使用 Docker 容器通过 docker-compose 命令进行开发。

示例

$ docker-compose run --rm default install  # install deps via composer
$ docker-compose run --rm default  # runs tests in container

连接到容器

$ docker-compose run --rm default bash # runs bash in container and attach tty

adamstipak / nette-rest-route

维护者

详细信息