README

此插件简化了 CakePHP 3 应用程序的 REST API 开发。它只需将控制器的输出转换为 JSON 响应。

安装

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

安装 composer 包的推荐方式是

composer require sprintcube/cakephp-rest

安装后，加载插件

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

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

$ bin/cake plugin load -b Rest

使用方法

在您的 CakePHP 应用程序中编写代码的方式无需进行重大更改。只需在路由配置中添加一个参数 isRest，例如：

$routes->connect('/foo/bar', ['controller' => 'Foo', 'action' => 'bar', 'isRest' => true]);

并将您的控制器扩展为 RestController，然后插件会自动处理一切。例如：

<?php

namespace App\Controller;

use Rest\Controller\RestController;

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

    /**
     * bar method
     *
     * @return Response|void
     */
    public function bar()
    {
        $bar = [
            'falanu' => [
                'dhikanu',
                'tamburo'
            ]
        ];

        $this->set(compact('bar'));
    }
}

就这样。您将看到以下响应。

{
    "status": "OK",
    "result": {
        "bar": {
            "falanu": [
                "dhikanu",
                "tamburo"
            ]
        }
    }
}

不是很简单吗？无论您使用 set() 方法从控制器的操作中设置什么 viewVars，都将转换为 JSON 响应。

响应格式

此插件以以下格式返回响应。

{
    "status": "OK",
    "result": {
        ...
    }
}

根据您的响应代码，status 键可能包含 OK 或 NOK。对于所有成功响应，代码将为 200，此键的值将为 OK。

在发生错误或异常的情况下，status 的值将变为 NOK。此外，根据您的应用程序的 debug 设置，它将包含异常和跟踪数据。

result 键包含实际响应。它包含您从控制器中设置的所有变量。在发生错误/异常的情况下，此键将不可用。

需要身份验证？

此插件还提供了一个选项，可以使用 JWT 对请求进行身份验证。只需在路由配置中添加一个额外的参数 requireAuthorization，例如：

$routes->connect('/foo/bar', ['controller' => 'Foo', 'action' => 'bar', 'isRest' => true, 'requireAuthorization' => true]);

现在，插件将检查请求中的 JWT 令牌，形式为标题、查询参数或表单数据。如果您想将令牌放在标题中，请使用以下格式。

Authorization: Bearer [token]

对于查询参数或表单数据，请使用 token 参数，并将令牌设置为参数的值。

生成令牌

如果您需要在 API 中进行身份验证，您必须首先将令牌授予执行 API 请求的用户。通常，当用户登录时，响应应包含所有后续请求的令牌。

要生成令牌，请使用插件 Utility 类中的方法：JwtToken::generate()。

/**
 * login method
 *
 * @return Response|void
 */
public function login()
{
    // you user authentication code will go here, you can compare the user with the database or whatever
    
    $payload = [
        'id' => "Your User's ID",
        'other' => "Some other data"
    ];

    $token = \Rest\Utility\JwtToken::generate($payload);

    $this->set(compact('token'));
}

它将在响应中返回令牌。因此，在下一个 API 调用中，用户可以使用该令牌进行授权。您可以在负载中添加所需的数据。

默认情况下，插件使用预定义的密钥和算法生成 JWT 令牌。您可以通过创建 config/rest.php 文件来更新此配置。此配置文件的内容如下：

<?php
return [
    'Rest' => [
        'jwt' => [
            'key' => 'PUT YOUR KEY HERE', // it should contain alphanumeric string with symbols
            'algorithm' => 'HS256' // See https://tools.ietf.org/html/draft-ietf-jose-json-web-algorithms-40
        ]
    ]
];

访问令牌数据

如果请求中存在有效的令牌，您可以在控制器中使用 token 和 payload 属性来访问它。

/**
 * view method
 *
 * @return Response|void
 */
public function view()
{
    $token = $this->token;

    $payload = $this->payload;

    // your action logic...
}

这些属性也存在于您控制器的 beforeFilter 方法中，因此您可以在那里添加额外的认证逻辑。

问题报告

如果您在使用此插件时遇到问题或发现任何错误，请在 GitHub 上提交问题。

pnglabz / cakephp-rest

维护者

详细信息