用于创建API的一组traits
在HLEB2框架中实现API时，提供了一组traits以简化控制器中的验证和数据处理（应用了这些traits的地方）。
在PHP中使用traits是众说纷纭的，这就是为什么这个模块被提供为一个单独的库，你可以选择使用； 市场上有相当多的验证器可用于在PHP中开发，这只是一个简单的工作替代品。
使用Composer安装库github.com/phphleb/api-multitool：
$composer require phphleb/api-multitool
或下载并解压库到文件夹/vendor/phphleb/api-multitool。
#连接BaseApiTrait（traits集合）
首先，你需要创建一个父类BaseApiActions（或其他名称）用于具有API的控制器：
// File /app/Controllers/Api/BaseApiActions.php
namespace App\Controllers\Api;
use Hleb\Base\Controller;
use Phphleb\ApiMultitool\BaseApiTrait;
class BaseApiActions extends Controller
{
// Adding a set of traits for the API.
use BaseApiTrait;
function __construct(array $config = [])
{
parent::__construct($config);
// Passing the debug mode value to the API constructor.
$this->setApiBoxDebug($this->container->settings()->isDebug());
}
}
所有辅助traits都被收集在BaseApiTrait作为一个集合中。 因此，只需将其连接到控制器就可以获得完整的实现。 如果需要不同的traits集合，可以将它们组合成一个新的集合。
在这个类继承的所有控制器中，集合中的每个trait的方法将会出现：
#ApiHandlerTrait
traitApiHandlerTrait包含几个可能有助于处理返回的API数据的方法。 这并不意味着其方法'present'和'error'构成最终的响应，它们返回命名的数组，可以根据更复杂的标准使用。 控制器方法中的示例：
// Файл /app/Controllers/Api/UserController.php
namespace App\Controllers\Api;
use App\Models\UserModel;
class UserController extends BaseApiActions
{
public function actionGetOne(): array
{
$id = $this->container->request()->get('id')->asInt();
if (!$id) {
return $this->error('Invalid request data: id', 400);
}
$data = UserModel::getOne($id);
return array_merge(
$this->present($data ?: []),
['error_cells' => $this->getErrorCells()]
);
}
}
在HLEB框架中，从控制器返回数组时会自动转换为JSON。 输出格式化数组时，会添加一个值'error_cells'，其中列出了发生验证错误的字段（如果有的话）。
#ApiMethodWrapperTrait
拦截系统错误并将其输出到此前的traitApiHandlersTrait的'error'方法，或者另一个指定为此目的的方法（如果未使用上述trait）。 如果调用控制器方法，为了正确处理其错误，需要在控制器中添加前缀'action'，而在路由中保持无前缀。例如，对于前面的控制器示例，路由大约如下：
这里需要注意的是，最初调用的是控制器方法'getOne'，而在控制器本身中，该方法是'actionGetOne'。
#ApiPageManagerTrait
实现了通常需要的分页功能。 添加'getPageInterval'方法，它将分页数据转换为更方便的格式。 这计算出选择的初始值，这对于与数据库协同工作很有帮助。
#ApiRequestDataManagerTrait
添加方法'check'，允许通过一个数组中的条件检查另一个数组中的数据。 使用此trait可验证转换为数组的任何传入数据，无论是POST请求参数还是JSON Body。 开发者可以编写条件列表来验证数据。 例如，HLEB2框架中的(Request::input()返回一个JSON Body数组):
$data = Request::input();
// $result - a boolean value indicating whether the checks were successful or not.
$result = $this->check($data,
[
'id' => 'required|type:int|min:1', // Required field, type integer, minimum value 1.
'email' => 'required|type:string', // Required field, type string.
'name' => 'type:string,null', // Optional field, but will check for type string or NULL if found.
'password' => 'required|type:string|minlength:6' // Required field, type string, minimum number of characters 6.
]);
$errorCells = $this->getErrorCells(); // An array with a list of fields that did not pass the check.
$errorMessage = $this->getErrorMessage(); // An array with messages about validation errors that occurred.
required - 必填字段，总是在开头位置。
可能的类型列表('type' - 必须位于第一位置或在required之后):
string - 检查是否有字符串值，可以限制为minlength和maxlength。
float - 检查类型是否为float(double)，限制可以为max和min。
int - 检查类型是否为int(integer)，限制可以为max和min。
regex - 检查正则表达式，例如'regex:[0-9]+'。
fullregex - 检查完整正则表达式，类似'fullregex:/^[0-9]+$/i'，必须用斜杠括起来，可以包含字符 : 和 |，与较简单的regex不同。
bool - 检查是否为布尔值，仅true或false。
null - 检查是否为null作为有效值。
void - 检查是否为空字符串作为有效值。
枚举类型:
enum - 在可能值中查找，例如'enum:1,2,3,4,south,east,north,west'。
等值检查不严格，因此4和'4'都是正确的；为了精确匹配，最好伴随类型检查。
您可以添加两种或更多类型，它们将被包含性地检查所有通用条件，例如'type:string,null,void|minlen:5' - 这意味着字符串应被检查，至少5个字符长，或者为空，或者null值。在所有其他情况下，它会返回false作为验证失败的结果。
您还可以检查具有标准数组字段列表的字段数组（它们将根据统一模板进行检查）：
[
// Optional field, array with enumeration (two fields are checked in each).
'users' => ['id' => 'required|type:int', 'name' => 'required|type:string'],
// Required field, array with enumeration (three fields are checked in each).
'images' => ['required', ['id' => 'required|type:int', 'width' => 'required|type:int', 'height' => 'required|type:int']]
]);
要检查检查数组中的嵌套数组的值，名称在方括号中指定。
[
['name1' => ['name2' => ['name3' => 'text']]],// Data.
['[name1][name2][name3]' => 'required|type:string'] // Array with conditions.
]);
上述条件将返回考虑嵌套性的成功检查。
#测试
API traits使用 github.com/phphleb/api-tests 进行测试。
