README

![稳定性][ico-stability]

此插件通过使用 CakePHP 的依赖注入容器 为您的 RESTful API 控制器操作提供 CRUD（创建/读取/更新/删除）服务。

• 大多数 CRUD 操作只需一行代码即可完成。
• 自动将数据序列化为 JSON、XML 等。
• 自动执行允许的请求 $this-request->allowMethod()
• Crud 与现有的 MixerApi 插件（包括分页和 CakePHP 搜索）很好地协同工作。
• 接口的使用允许您在以后使用自己的具体实现。
• 需要兼容 CakePHP ^4.2 的项目。

您还可以查看 CakePHP Crud，它不依赖于依赖注入。如果您在没有 MixerApi/ExceptionRender 或非 API 项目中使用此插件，请参阅下面的其他用途。

安装

composer require mixerapi/crud
bin/cake plugin load MixerApi/Crud

另外，在 composer 安装后，您可以手动在应用程序中加载此插件

# src/Application.php
public function bootstrap(): void
{
    $this->addPlugin('MixerApi/Crud');
}

有关其他配置，请参阅插件选项。

用法

启用后，以下服务可以注入到您的控制器操作中。

use MixerApi\Crud\Interfaces\{CreateInterface, ReadInterface, UpdateInterface, DeleteInterface, SearchInterface};

所有 CRUD 服务都从控制器中推断表名，您可以通过调用 setTableName($name) 方法来更改表名。

如果您使用的是 MixerApi\ExceptionRender，则事件将捕获验证错误并为您处理响应，否则将抛出 MixerApi\Crud\Exception\ResourceWriteException。

有关路径参数的说明，如果您的路径参数不是 id。

创建

public function add(CreateInterface $create)
{
    $this->set('data', $create->save($this));
}

注意，支持带有 $options 的 save()。

return $create->save($this, [
    'accessibleFields' => [
        'password' => true,
    ]
]);

读取

public function view(ReadInteface $read)
{
    $this->set('data', $read->read($this));
}

注意，支持带有 $options 的 read()。

return $read->save($this, ['contains' => ['OtherTable']]);

返回 CakePHP Query 对象

$query = $read->query($this)

更新

public function edit(UpdateInterface $update)
{
    $this->set('data', $update->save($this));
}

注意，支持带有 $options 的 update()。

return $update->save($this, [
    'accessibleFields' => [
        'password' => true,
    ]
]);

删除

public function delete(DeleteInterface $delete)
{
    return $delete->delete($this)->respond(); // calling respond() is optional
}

注意，支持带有 $options 的 delete()。

return $delete->delete($this, ['atomic' => false]);

搜索

搜索服务与 分页 以及可选的 CakePHP 搜索 协同工作。

示例

public function index(SearchInterface $search)
{
    $this->set('data', $search->search($this));
}

要使用 CakePHP 搜索，在控制器中的 initialize() 方法中正常初始化组件。

$this->set('data', $search->search($this));

对于自定义 CakePHP 搜索集合，请调用 setCollection($name) 方法

$this->set('data', $search->setCollection('collection_name')->search($this));

返回 CakePHP Query 对象

$query = $search->query($this);

序列化

序列化由 Controller.beforeRender 监听器处理。它序列化所有 CRUD 操作的第一个视图变量，并且不会对非 CRUD 操作运行。有关禁用序列化的说明，请参阅选项。

允许的 HTTP 方法

允许的方法由 Controller.initialize 监听器处理。有关禁用或修改默认值的说明，请参阅插件选项。

您还可以在任意服务上调用 setAllowMethods($methods) 以覆盖默认行为。此方法接受字符串或任何数组作为参数，就像本机 $request->allowedMethods() 一样。

插件选项

您可以通过在添加插件时传递一个选项数组来自定义功能。

# src/Application.php

public function bootstrap(): void
{
    $this->addPlugin('MixerApi/Crud', $options);
}

自定义允许的 HTTP 方法

$options = [
    'allowedMethods' => [
        'add' => ['post'],
        'edit' => ['patch'],
        'delete' => ['delete'],
    ]
];

要完全禁用自动 $request->allowMethod()

$options = [
    'allowedMethods' => []
];

禁用自动序列化

$options = [
    'doSerialize' => false, // default is true
];

其他

路径参数

如果您的资源路径参数不是 id，则将标识符作为第二个参数传递

public function view(ReadInteface $read, string $id)
{
    $this->set('data', $read->read($this, $id));
}

上述内容也适用于更新和删除。

其他用法

此插件与使用 MixerApi/ExceptionRender 的 API 项目配合使用最佳，该插件使用事件在发生错误时设置响应。如果您的项目没有使用 ExceptionRender 或您不是 API，您可以编写自定义异常渲染器，并查找 ResourceWriteException，然后使用 EntityInterface 从 ResourceWriteException::getEntity() 修改 viewVars 输出。

有关更多信息，请阅读 CakePHP 自定义 ExceptionRenderer 文档。