README

一个轻量级的基于PHP的REST API框架

为PHP 7.4和8.0编写

如何使用

将Phapi添加到您的项目中

安装
```
composer require jacob-roth/phapi
```

index.php

$Routes = new \Phapi\Routes();
$Routes->Add(new \Phapi\Route(
  "Default",
  "/api/v1/{controller}/{action}"
));

$Startup = new \Phapi\Startup($Routes);
$Startup->Run();

.htaccess

<IfModule mod_rewrite.c>
  Options +FollowSymLinks
  RewriteEngine On
  RewriteRule !index.php index.php
</IfModule>

添加API端点

创建一个新的以"Controller"结尾的PHP类，该类继承自Phapi\Controller（或使用现有的Controller类）
```
class DefaultController extends \Phapi\Controller
```
添加一个public方法作为新的端点
- 此方法可以命名为任何您想要的名称，或者可以命名为HTTP请求方法（这将允许您在URL中不需要指定方法的情况下调用端点）
- 在此方法内部，您需要指定HTTP请求方法（Get、Put等）。虽然不是强制性的，但这是一个好的做法。
```
// This endpoint can be called like
// PUT /Default/IdPut/2
public function IdPut(int $id)
{
  $this->HttpPut();
  return [
    "id" => $id
  ];
}

// This endpoint can be called like
// GET /Default/2
public function GET(int $id)
{
  $this->HttpGet();
  return "something";
}
```
在index.php中添加一个与您的新的端点相匹配的路由（请注意，可能已经存在一个现有的路由，因此添加新的路由可能不是必要的）
- 路由将请求映射到端点
- 添加路由时，可以在URL中指定变量，如{id}。其中两个变量不能使用：controller和action，它们指定了要使用的控制器类和方法。可以通过在前面加上一个"?"使路由变量成为可选的，如{?id}
- 您可以在路由中指定允许的HTTP请求方法
- 在将路由映射到端点时，可以指定命名空间、类，甚至方法
- 这是使用路由的概述。有关更多详细信息，请参阅类规范 > 路由部分

类规范

控制器

指定允许的HTTP请求方法。每个端点只使用一个。以下是一些示例
```
$this->HttpGet();
$this->HttpPut();
$this->HttpPost();
$this->HttpDelete();
```

更改返回的HTTP响应代码

$this->SetResponseCode(\Phapi\HttpCode::Created);

路由
- 您只需要在index.php中初始化Route对象。因为这个对象可能很复杂，所以我会逐一介绍构造函数参数
- 构造函数如下所示
```
public function __construct(
  string $Name,
  string $Path,
  ?array $HttpMethods = null,
  string $Namespace = "",
  ?string $DefaultController = null,
  ?string $DefaultAction = null
)
```
  - Name除了用户用来跟踪每个路由的使用情况外，不使用。您可以在其中输入任何字符串值。
  - Path是用于匹配请求URL中路径的模式。
    - 例如，如果您的路径是/v1/{controller}/{action}，那么以下每个都将是正确的
      - /v1/default/getValues将映射到方法DefaultController->getValues()。
      - /v1/user/login将映射到UserController->login()
    - 以下每个都不会映射，而是返回404
      - /user/login
      - /default/getValues
      - /v1/user/login/somethingElse
    - 路径的一个重要特性是变量。路径变量用于将数据从请求URL传递到方法调用。
      - 具体来说，定义路径变量的字符串需要与端点方法的参数中使用的字符串相同
      - 例如，给定以下方法
        
        public function IdGet(int $id)
        
        路径必须包含{id}才能正确调用端点。这样的路径可以像这样：/api/v1/{controller}/{action}/{id}
      - 如您可能已经注意到的，有一些特殊的路径变量。特别是，"controller"和"action"。您可以在您的应用程序中适当使用它们，但是将方法参数命名为controller会导致将错误的数据传递到端点。我强烈建议在生产环境中不要这样做。
      - 您还可以使路径变量可选。只需在路径变量字符串中添加一个 "?"，例如 {?id}，并确保该方法允许将该参数传递为 null 值。例如
        
        public function IdGet(?int $id)
        
        使用可选变量可以使您执行映射，其中 /v1/default/idGet/123 和 /v1/default/idGet/ 都映射到 DefaultController->IdGet($id)，其中后者简单地传递 null 作为 $id
  - HttpMethods 允许您限制在路由中使用的 HTTP 请求方法。
    - 如果您想将路由 /v1/{controller}/{action} 限制为仅 GET 和 POST 请求，您将使用
```
[\Phapi\HttpMethod::Get, \Phapi\HttpMethod::Post]
```
    - 默认值，null，的行为与
```
\Phapi\HttpMethod::All
```
  - Namespace 允许您将请求映射到给定命名空间中的控制器。如果您的控制器类不在命名空间中，请将其留空
    - 例如，给定以下路由
```
$Routes->Add(new \Phapi\Route(
  "Default",
  "/api/v1/{controller}/{action}",
  \Phapi\HttpMethod::All,
  "V1"
));
```
      输入 /v1/user/login 会映射到 V1\UserController->login()
  - DefaultController 和 DefaultAction 在控制器类和端点方法可选或未由请求 URL 指定时很有用。
    - 例如，以下路由
```
$Routes->Add(new \Phapi\Route(
  "Calling Methods with Special URLs",
  "/{id}",
  null,
  "V2",
  "Special",
  "DoingSomethingSpecial"
));
```
      将映射到 V2\SpecialController->DoingSomethingSpecial($id)
ApiException
- 可以在遇到错误时抛出，Phapi 将处理异常
- 如果您想向调用者返回某些内容，可以指定 HTTP 响应代码和消息字符串
- 示例
```
throw new \Phapi\ApiException(\Phapi\HttpCode::BadRequest, "Invalid Input Data");
```

HttpMethod

代表 HTTP 请求方法的常量集合

\Phapi\HttpMethod::Get
\Phapi\HttpMethod::Head
\Phapi\HttpMethod::Post
\Phapi\HttpMethod::Put
\Phapi\HttpMethod::Delete
\Phapi\HttpMethod::Connect
\Phapi\HttpMethod::Options
\Phapi\HttpMethod::Trace
\Phapi\HttpMethod::Patch
\Phapi\HttpMethod::All

HttpCode

代表 HTTP 响应代码的常量集合

由于有很多，这里不会列出所有内容，但这里有一些示例

\Phapi\HttpCode::Ok          // 200
\Phapi\HttpCode::Created     // 201
\Phapi\HttpCode::NotFound    // 404

向端点传递数据

有两种方法可以将数据从请求传递到端点：通过请求数据和请求 URL

请求数据中传递的数据
- 如果您想将请求数据传递到端点，只需添加任何名称和任何 PHP 对象类型的参数。这可以是 "object" 或自定义对象。
- 示例
```
public function EchoId(RequestObject $req)
{
  $this->HttpPost();
  return [
    "id" => $req->id
  ];
}
```
请求 URL 中传递的数据
- 传递到 URL 的数据由路径变量处理。有关详细信息，请参阅 类规范 > 路由 > 路径

版本限制（计划升级）

目前，输入和输出数据只能为 JSON。在未来的版本中，我打算添加一种方法，可以根据 "Content-Type" 和 "Accept" HTTP 头部覆盖 I/O 格式
说到 HTTP 头部，这里有很多改进的空间。目前，Phapi 在处理数据时使用了零个这些头部。像 Content-type、Accept、Accept-Encoding、Authorization、Cookie 和所有 CORS 相关的内容都可以在 Phapi 中使用。目前没有计划添加除 Content-type 和 Accept 之外的内容，但这个考虑是存在的。

jacob-roth / phapi

维护者

详细信息

README

如何使用

将Phapi添加到您的项目中

添加API端点

类规范

向端点传递数据

版本限制（计划升级）