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 请求的用户。通常，当用户登录时，响应应该包含用于所有后续请求的令牌。

要生成令牌，请使用插件实用工具类中的方法： 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 上提交问题。

sprintcube / cakephp-rest

维护者

详细信息