README

⚠️ 3.0 分支正在进行文档整理。实现和测试已更新，但已删除一些在 2 系列中可用的功能。

要求

CakePHP 3.1*
PHP 5.5+

概述

这是一个用于在 CakePHP 中实现 REST API 的组件和其附属库集合。基本上，只需安装组件并在 Routing.prefixes 中包含 'api' 即可使用。

设置

• 在 app/Config/routes.php 中创建以下路由

Router::prefix('api', function ($routes) {
    // ルート定義
});

• 在 app/config/bootstarp.php 中设置 Plugin::load('Api'); OR Plugin::loadAll()
• 在要使用的控制器(OR AppController)中进行以下设置

$components = [
	'Api.Api'
];
// または
$this->loadComponent('Api.Api');

编码示例

新用户注册（电子邮件地址）

/**
 * signup api
 *
 * @return void
 */
public function signup()
{
	$this->request->onlyAllow('post');
	$this->Api->recordMap = [
		'User' => [
			'name',
			'email',
			'password',
		],
	];
	$params = $this->Api->requireParamsFromMap();
	$data = $this->Api->paramsToRecord($params);

	$this->Api->processSaveRecord($data, [
		'saveCallback' => [$this->User, 'signup'],
	]);
}

登录

/**
 * login api
 *
 * @return void
 */
public function login()
{
	$this->request->onlyAllow('post');

	$data = $this->Api->requireParams([
		'email',
		'password',
	]);
	$this->request->data = ['User' => $data];
	$this->Auth->logout();
	$this->User->useValidationSet(['Login']);
	$this->User->create($this->request->data);
	$loggedIn = $this->User->validates() && $this->Auth->login();
	if ($loggedIn) {
		$this->Api->success();
	} else {
		$this->Api->raiseValidationErrors();
	}
}

获取评论

App::uses('LackParametersException', 'Api.Error');

Class CommentsController extends AppController {

	/**
	 * index api
	 *
	 * @return void
	 */
	public function api_index($postId = null) {
		$this->request->onlyAllow('get');
		if ($postId === null) {
			throw new LackParametersException('postId');
		}

		$this->Api->recordMap = [
			'Comment' => [
				'id',
				'body',
				'created',
				'updated',
			],
			'User' => [
				'_wrap' => 'user',
				'id',
				'name',
			],
		];

		$this->Comment->create();
		$this->Comment->set('post_id', $postId);
		if (!$this->Comment->validates(['fieldList' => ['post_id']])) {
			$this->Api->recordMap = ['Comment' => ['post_id']];
			return $this->Api->processValidationErrors();
		}

		$limit = 20;
		$page = $this->Api->collectParam('page');
		$page = $page ? (int)$page : 1;
		$contain = ['User'];
		$comments = $this->Comment->findAllByPostId($postId, compact('limit', 'page', 'contain'));

		foreach ($comments as &$comment) {
			$comment = $this->Api->recordToParams($comment);
		}
		$this->Api->success(compact([
			'page',
			'limit',
			'comments',
		]));
	}

}

处理请求

将请求参数作为 GET 时的查询字符串处理，其他情况则处理 POST body。也可以说成是查看 $this->request->query 或 $this->request->data。

响应概要

• 仅支持 JSON。
• 响应结构是固定的。

响应示例（成功）

{
    "success": true,
    "code": 200,
    "data": {
        "user": {
            "id": "2081",
            "last_name": "shimizu",
            "first_name": "hiroki"
        },
    }
}

响应示例（失败）

{
    "success": false,
    "code": 400,
    "errorCode": "validation_error",
    "errorMessage": "バリデーションエラー",
    "validationErrors": {
        "id": [
            [
                "exists",
                "valid"
            ]
        ]
    }
}

注意事项

• 并非通用设计。
• 难以应用于现有应用程序
• 部分功能未文档化且不完整（如 habtm、hasMany 对应等）
  • 通常使用没有问题