README

一个用于自定义 API 路由的插件。由 Howatson+Co. 用爱制作。

用法

使用此插件有两个部分

1. 定义 API 路由
2. 定义处理响应逻辑的自定义控制器

要执行这些操作中的任何一个，您首先需要访问 Rest API Server 类的实例。这可以通过调用全局作用域函数 HCRR 如下实现

$server = HCRR();

或者，通过访问全局作用域变量

global $hcrr;

定义路由

您可以通过附加到 Router 类的 registerRoute 方法来定义一个路由，如下所示

$server->router->registerRoute("/test", "\TestController", "index");

registerRoute 方法接受三个参数

• 此路由执行时需要匹配的 API URI 模式。这可以是一个正则表达式字符串。
• 要实例化的控制器的名称。
• 附加到控制器的要执行的方法的名称。

定义控制器

在定义控制器时，请遵循以下规则

• 控制器必须扩展 \HC\RestRoutes\Abstracts\ControllerAbstract
• 控制器方法应命名为 ${name}_${httpVerb}，其中
  • name 是您传递给路由的名称，
  • httpVerb 是请求的 HTTP 动词（例如 GET、POST、PUT 等）
• 返回 您想要响应的数据。
• 抛出 RestfulException 以处理异常。

见下面的示例

class TestController extends \HC\RestRoutes\Abstracts\ControllerAbstract
{
  public function index_get()
  {
    $posts = get_posts();

    // This will send a 200 response to the client side
    // with the data payload attached
    if (!empty($posts)) {
      return $posts;
    }

    // Otherwise, you can handle exceptions like this
    throw new \HC\RestRoutes\Exceptions\NotFoundException("No posts found.");
  }
}

接下来，我们需要注册控制器。

要注册控制器，请使用 ControllerFactory 类的 register 方法

$server->router->controllerFactory->register("\TestController");

完整示例

将这些放在一起，一个示例可能看起来像这样

class TestController extends \HC\RestRoutes\Abstracts\ControllerAbstract
{
  public function index_get()
  {
    $posts = get_posts();

    // This will send a 200 response to the client side
    // with the data payload attached
    if (!empty($posts)) {
      return $posts;
    }

    // Otherwise, you can handle exceptions like this
    throw new \HC\RestRoutes\Exceptions\NotFoundException("No posts found.");
  }
}

$server = HCRR();
$server->router->controllerFactory->register("\TestController");
$server->router->registerRoute("/test", "\TestController", "index");

额外

授权

为了确保端点只向授权用户提供完整的有效负载，您可以使用附加到 \HC\RestRoutes\Abstracts\ControllerAbstract 类的 validateAdmin 和 validateEditor 方法。

定义 API 前缀

默认 API 前缀是 /api/hcrr。您可以通过在 \HC\RestRoutes\Router 类上使用 setPrefix 方法来自定义此前缀。

$server->router->setPrefix("/your/custom/prefix");