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',
];

• 使用MySQL的DATE()函数将请求中的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