README

Supaapps Laravel 项目的样板和助手

目录

• 安装
• 用法
  • 生成 CRUD 控制器
  • CRUD
  • 可用的 CRUD 属性
  • CrudIndexTrait 使用的属性
  • UpdateIndexTrait 使用的属性
  • DeleteIndexTrait 使用的属性
• CRUD 控制器覆盖
  • 在 CrudIndexTrait 中覆盖方法
• 用户签名
• 测试
• 代码风格检查
• 有用的链接

安装

composer require supaapps/supaapps-laravel-api-kit

用法

生成 CRUD 控制器

要创建 CRUD 控制器，请运行以下命令

php artisan make:crud-controller

CRUD

要利用 CRUD 样板控制器，请在您的控制器中扩展 BaseCrudController。 示例

use Supaapps\LaravelApiKit\Controllers\BaseCrudController;

class ExampleController extends BaseCrudController
{
    public string $model = \App\Models\Example::class; // replace with your model
}

可用的 CRUD 属性

您可以在 CRUD 控制器中使用多个属性

• CRUD 操作的模型。（必需）

public string $model = \App\Models\Example::class; // replace with your model

CrudIndexTrait 使用的属性

• 是否对索引响应进行分页。

public bool $shouldPaginate = false;

• 使用请求中的 search 参数在单个列上执行搜索。 如果您想搜索多个列，请使用 $searchSimilarFields，见下一个属性。

public ?string $searchField = null; // replace with desired column

以下所有属性应为数组。如果您想在 CRUD 控制器中添加一些逻辑，请转到 CRUD 控制器覆盖

• 使用请求中的 search 参数和 LIKE 操作符在指定的列中执行相似结果的查找。

public array $searchSimilarFields = [];

在以下示例中，它将 name 或 description 中的 %supa% 作为查找

// user hit endpoint > /example?search=supa

public array $searchSimilarFields = [
    'name',
    'description',
];

• 使用请求中的 search 参数和 = 操作符在指定的列中执行精确结果的查找。

public array $searchExactFields = [];

在以下示例中，它将 id、price 或 category_id 中的 1 作为查找

// user hit endpoint > /example?search=1

public array $searchExactFields = [
    'id',
    'price',
    'category_id',
];

• 使用 DATE() MySQL 函数将请求中的 search 参数包装在指定的列中进行查找。

public array $searchDateFields = [];

在以下示例中，它将 completed_at、created_at 或 updated_at 中的 2023-09-26 作为查找

// user hit endpoint > /example?search=2023-09-26

public array $searchDateFields = [
    'completed_at',
    'created_at',
    'updated_at',
];

• 根据给定的值精确筛选列。

public array $filters = [];

在以下示例中，它将应用查询 WHERE id IN (1, 2) AND code IN ('ABC')

// user hit endpoint > /example?ids[]=1&ids[]=2&codes[]=ABC

public array $filters = [
    'ids',
    'codes',
];

• 按最小和最大值筛选日期列

public array $dateFilters = [];

在以下示例中，它将搜索 created_at 大于 create_at_min 且小于 created_at_max 的记录，以及 updated_at 大于 updated_at_min

// user hit endpoint > /example?created_at_min=2023-09-01&created_at_max=2023-09-30&updated_at_min=2023-09-15

public array $dateFilters = [
    'created_at',
    'updated_at',
];

• 筛选 NULL 或 NOT NULL 的列

public ?array $isEmptyFilters = [];

在以下示例中，用户想要获取完成且未取消的奖励。这些奖励具有 completed_at IS NOT NULL 和 cancelled_at IS NULL

// user hit endpoint > /example?is_empty[completed_at]=false&is_empty[cancelled_at]=true

public ?array $isEmptyFilters = [
    'completed_at',
    'cancelled_at',
];

• 定义默认排序列

public ?array $defaultOrderByColumns = null;

在以下示例中，控制器中定义了 2 个排序规则。结果将按 created_at 降序和按 id 升序排序。

public ?array $defaultOrderByColumns = [
    'created_at,desc',
    'id,asc'
];

但如果请求有 sort 查询参数，则将覆盖 defaultOrderByColumns。 示例

/sort?sort[id]=desc&sort[name]=asc

这将首先按 id 降序排序，然后按 name 升序排序

UpdateIndexTrait 使用的属性

• 禁用模型上的更新

public bool $readOnly = false;

DeleteIndexTrait 使用的属性

• 启用模型上的删除

public bool $isDeletable = false;

CRUD 控制器覆盖

如果您想为属性添加更多逻辑，您可以使用getter在控制器中重写属性。例如：根据条件返回不同的$searchExactFields。

private function getSearchExactFields(): array
{
    if (request('user_type') == 'admin') {
        return [
            'admin_id'
        ];
    }

    return [
        'user_id'
    ];
}

在 CrudIndexTrait 中覆盖方法

• 重写$searchSimilarFields

private function getSearchSimilarFields(): array;

• 重写$searchExactFields

private function getSearchExactFields(): array;

• 重写$searchDateFields

private function getSearchDateFields(): array;

• 重写$filters

private function getFilters(): array;

• 重写$dateFilters

private function getDateFilters(): array;

• 重写$isEmptyFilters

private function getIsEmptyFilters(): array;

• 获取可以按顺序排列的允许列表

// by default, it merges the values from:
//    $this->getSearchSimilarFields(),
//    $this->getSearchExactFields(),
//    $this->getSearchDateFields()
private function getOrderByColumns(): array;

• 重写$defaultOrderByColumns

private function getDefaultOrderByColumns(): ?array;

用户签名

您可以在3个步骤中跟踪模型中created和updated的用户

1. 将所需的列包含到模型的schema中

Schema::table('articles', function (Blueprint $table) {
    $table->auditIds();
});

auditIds接受2个参数

• table：相关表名，默认：users
• column：相关表上的相关列名，默认：id

1. 将自定义列包含到模型的$fillable属性中

protected $fillable = [
    'created_by_id',
    'updated_by_id',
    ...
]

1. 为模型添加观察者

// in src/Providers/EventServiceProvider.php add the following line

protected $observers = [
    \App\Models\Article::class => [ // replace Article with your model
        \Supaapps\LaravelApiKit\Observers\UserSignatureObserver::class,
    ],
    ...
];

测试

composer test

代码风格检查

composer lint

有用的链接

• https://www.laravelpackage.com/
• https://github.com/orchestral/testbench
• https://github.com/jfcherng/php-diff