README

此插件为您的 CakePHP 3 应用程序提供构建 REST API 服务的基本支持。

要求

此插件有以下要求

CakePHP 3.0.0 或更高版本。
PHP 5.4.16 或更高版本。

安装

您可以使用 composer 将此插件安装到您的 CakePHP 应用程序中。

安装 composer 包的推荐方式是

composer require pejonic/cakephp-3-rest-api

安装后，加载插件

Plugin::load('RestApi', ['bootstrap' => true]);

或者，您可以使用 shell 命令来加载插件

$ bin/cake plugin load -b RestApi

用法

您只需创建一个与 API 相关的控制器，并将其扩展到 ApiController 而不是默认的 AppController。您只需在 apiResponse 变量中设置您的结果，并在 httpStatusCode 变量中设置您的响应代码。例如，

namespace App\Controller;

use RestApi\Controller\ApiController;

/**
 * Foo Controller
 */
class FooController extends ApiController
{

    /**
     * bar method
     *
     */
    public function bar()
    {
		// your action logic

		// Set the HTTP status code. By default, it is set to 200
		$this->httpStatusCode = 200;

		// Set the response
		$this->apiResponse['you_response'] = 'your response data';
    }
}

您可以在动作函数中根据您的需要定义逻辑。对于上面的示例，您将得到以下格式的响应，

{"status":"OK","result":{"you_response":"your response data"}}

上述示例的 URL 将是 http://yourdomain.com/foo/bar。您可以通过设置 APP/config/routes.php 中的路由来自定义它。

简单 :)

配置

cors

截至目前，此插件提供 CORS 请求的配置。默认情况下，cors 请求已启用，并允许来自所有域的请求。您可以通过在 APP/config/api.php 中创建配置文件来覆盖这些设置。文件的内容如下所示，

<?php
return [
    'ApiRequest' => [
        'cors' => [
            'enabled' => true,
            'origin' => '*'
        ]
    ]
];

要禁用 cors 请求，将 enabled 标志设置为 false。要允许来自特定域的请求，在 origin 选项中设置它们，

<?php
return [
    'ApiRequest' => [
        'cors' => [
            'enabled' => true,
            'origin' => ['localhost', 'www.example.com', '*.example.com']
        ]
    ]
];

响应格式

API 的默认响应格式为 json，其结构如下所示。

{
  "status": "OK",
  "result": {
    //your result data
  }
}

如果您将 httpResponseCode 设置为任何非 200 的值，则 status 值将为 NOK，否则为 OK。在发生异常的情况下，它将自动处理并设置适当的状态码。

示例

以下是一些示例，以了解此插件的工作方式。

检索文章

让我们创建一个 API，它返回一个包含基本详情（如 id 和标题）的文章列表。我们的控制器将如下所示，

<?php

namespace App\Controller;

use RestApi\Controller\ApiController;

/**
 * Articles Controller
 *
 * @property \App\Model\Table\ArticlesTable $Articles
 */
class ArticlesController extends ApiController
{

    /**
     * index method
     *
     */
    public function index()
    {
        $articles = $this->Articles->find('all')
            ->select(['id', 'title'])
            ->toArray();

        $this->apiResponse['articles'] = $articles;
    }
}

上述 API 调用的响应将如下所示，

{
  "status": "OK",
  "result": {
    "articles": [
      {
        "id": 1,
        "title": "Lorem ipsum"
      },
      {
        "id": 2,
        "title": "Donec hendrerit"
      }
    ]
  }
}

异常处理

此插件将处理从您的动作抛出的异常。例如，如果您的 API 方法仅允许 POST 方法，而有人发起 GET 请求，它将生成包含正确 HTTP 响应代码的 NOK 响应。例如，

<?php

namespace App\Controller;

use RestApi\Controller\ApiController;

/**
 * Foo Controller
 *
 */
class FooController extends ApiController
{

    /**
     * bar method
     *
     */
    public function restricted()
    {
        $this->request->allowMethod('post');
        // your other logic will be here
        // and finally set your response
        // $this->apiResponse['you_response'] = 'your response data';
    }
}

响应将如下所示，

{"status":"NOK","result":{"message":"Method Not Allowed"}}

另一个抛出异常的示例，

<?php

namespace App\Controller;

use Cake\Network\Exception\NotFoundException;
use RestApi\Controller\ApiController;

/**
 * Foo Controller
 *
 */
class FooController extends ApiController
{

    /**
     * error method
     *
     */
    public function error()
    {
        $throwException = true;

        if ($throwException) {
            throw new NotFoundException();
        }

        // your other logic will be here
        // and finally set your response
        // $this->apiResponse['you_response'] = 'your response data';
    }
}

响应将是，

{"status":"NOK","result":{"message":"Not Found"}}

报告问题

如果您对此插件有任何问题或任何错误，请在 GitHub 上打开一个问题。

pejonic / cakephp-3-rest-api

维护者

详细信息