README

此存储库是我维护的一个工作项目的必需品，遗憾的是，维护者在2.0.0版本之后删除了hasRepository和BaseRepository。

Laravel API 控制器

默认情况下，可以扩展模型的基本CRUD API方法，包括列表、显示、更新、添加和删除端点，以便与模型进行交互。

安装

通过composer安装

composer require phpsa/laravel-api-controller

发布配置文件（可选 - 如果您需要更改任何默认配置）

php artisan vendor:publish --provider="Phpsa\LaravelApiController\ServiceProvider" --tag="config"

使用方法

通过php artisan make:api {ModelName}生成新的API控制器、存储库和路由

这将为您创建一个Api/ModelNameController，并为您设置以下基本路由

GET api/v1/{model_name} - 列出所有/分页/过滤（class::index）
GET api/v1/{model_name}/$id - 显示指定id（class::show）
POST api/v1/{model_name} - 插入新记录（class::store）
PUT api/v1/{model_name}/$id - 更新现有记录（class::update）
DELETE api/v1/{model_name}/$id - 删除现有记录（class::destroy）

您可以通过简单地添加自己的方法来覆盖这些方法，方法名在上面的括号中

事件

POST（class::store）- 触发新的Phpsa\LaravelApiController\Events\Created事件，其中新记录作为$record可用
PUT（class::update）- 触发新的Phpsa\LaravelApiController\Events\Updated事件，其中更新后的记录作为$record可用
DELETE（class::destroy）- 触发新的Phpsa\LaravelApiController\Events\Deleted事件，其中被删除的记录作为$record可用

策略

策略: https://laravel.net.cn/docs/6.x/authorization#generating-policies

使用php artisan make:policy PostPolicy --model=Post生成

获取列表 - 调用viewAny策略
获取单个 - 调用view策略
新建 - 调用create策略
更新 - 调用update策略
删除项 - 调用delete策略

策略中的查询/数据修改器用于API端点

qualifyCollectionQueryWithUser($user, $repository) -> 返回 void - 向存储库添加任何查询（例如 ->where('x','))
qualifyItemQueryWithUser($user, $repository)-> 返回 void - 向存储库添加任何查询（例如 ->where('x','))
qualifyStoreDataWithUser($data) - 返回更新的数据数组
qualifyUpdateDataWithUser($data) - 返回更新的数据数组

资源/集合（转换）

资源: https://laravel.net.cn/docs/6.x/eloquent-resources

使用php artisan make:apiresource UserResource和php artisan make:resource UserCollection生成

将资源扩展为

使用Phpsa\LaravelApiController\Http\Resources\ApiResource作为您的资源，使用Phpsa\LaravelApiController\Http\Resources\ApiCollection作为您的资源集合

在您的控制器中覆盖以下参数

	protected $resourceSingle = UserResource::class;
	protected $resourceCollection = UserCollection::class;

蛇形与驼峰

将所有驼峰转换为蛇形的中间件：Phpsa\LaravelApiController\Http\Middleware\SnakeCaseInputs
将请求头X-Accept-Case-Type设置为snake或camel，以更改您的数据响应

过滤

对于get命令，您可以使用以下URL模式进行过滤

在/不在

您可以将值数组传递给过滤器，例如：filter[user_id]=1||2||||4||7或filter[user_id!]=55||33

空/非空（从1.23.0版引入）

如果您需要过滤字段是否为空或非空，从1.23.0版开始可以使用过滤器参数。例如：filter[age]=NULL或filter[age!]=NULL。注意，NULL必须为大写。

旧版本给您的模型添加一个范围：例如

public function scopeAgeNull(Builder $builder, $isNull = true){
  $isNull ? $builder->whereNull('age') : $builder->whereNotNull('age');
}

将其添加到您的allowedScopes中，然后可以在URL中作为?ageNull=1（表示为空）和?ageNull=0（表示非空）进行调用

作用域

除了过滤外，您还可以使用Laravel的Eloquent 查询作用域进行更复杂的搜索或过滤。只需将$allowedScopes添加到您的ApiResource中，该作用域将作为查询参数公开。

假设您在Eloquent模型上定义了一个scopeFullname，您可以将此作用域公开给API如下所示

protected static $allowedScopes = [
  'fullname'
];

给定上述$allowedScopes数组，您的API消费者现在可以请求?fullname=John。查询参数值将传递到您的Eloquent模型中的作用域函数。

过滤相关模型

您可以使用任何配置了include的相关模型轻松进行过滤。只需在查询字符串中指定?filter[model.field]=123即可。上述相同的过滤器选项适用于相关字段。

字段、关系、排序和分页

字段

默认情况下返回所有字段，您可以通过以下方式将其限制为特定字段

API控制器参数$defaultFields默认为protected $defaultFields = ['*']; - 切换到包含字段数组
URL查询字符串中的fields参数：例如fields=id,name,age = 将只返回这些字段，这也会覆盖上述设置。
在您的响应资源中，您可以设置static::allowedFields以锁定可返回的字段
URL查询字符串中的addfields和removefields参数将与这些一起工作。
使用Laravel eloquent模型$appends属性来自动包含自定义属性访问器。

关系

使用在您的模型中定义的关系，您可以传递一个逗号分隔的列表，例如include=join1,join2，这将返回这些连接（一个或多个）。

只需将protected static $mapResources添加到您的Resource中，以定义要分配相关数据的关系资源。例如，对于一对一关系，应指定一个集合，对于一对多关系，直接指定相关资源。这将允许API正确格式化相关记录。

    protected static $mapResources = [
        'notes' => NotesCollection::class,
        'owner' => OwnerResource::class
    ];

您可以为大多数类型的关系自动更新和创建相关记录。只需在POST或PUT请求中包含相关资源名称即可。

对于BelongsToMany或MorphToMany关系，您可以选择同步策略。默认情况下，这将采用添加策略。也就是说，发送的关联记录将被添加到任何现有的关联记录中。在每次请求的基础上，您可以选择同步策略，这将删除请求中未列出的任何关联记录的枢轴。注意，实际的相关记录将不会被删除，只是枢轴条目。

要选择同步行为，请设置请求中的?sync[field]=true。

排序

排序也可以通过逗号分隔的列表传递，例如 sort=age asc 或 sort=age asc,name desc,eyes —— 分别生成 SQL sort age asc 和 sort age asc, name desc, eyes asc。
默认排序也可以在控制器中添加，通过覆盖 protected $defaultSort = null; 参数。

分页

可以在控制器中通过覆盖 protected $defaultLimit = 25; 来启用/禁用分页。
分页也可以通过 URL 传递，使用 limit=xx&page=y。
分页还可以通过覆盖 protected $maximumLimit = false; 参数来限制每页的最大记录数。

验证

在提交新记录时，可以通过添加一个返回数组的 rulesForCreate 方法到控制器中来执行验证。

[
    'email' => 'required|email',
    'games' => 'required|numeric',
]

请参阅 https://laravel.net.cn/docs/5.8/validation#conditionally-adding-rules

更新记录时，按照上述方式添加一个 rulesForUpdate 方法。

默认值

以下参数在 Base Api 控制器中设置，可以根据情况在您的控制器中覆盖

已弃用 protected $resourceKeySingular = 'data';
已弃用 protected $resourceKeyPlural = 'data';
protected $resourceSingle = JsonResource::class; 用于您的单资源集合
protected $resourceCollection = ResourceCollection::class; 用于您的资源集合集合
protected $defaultFields = ['*']; 默认响应字段
protected $defaultSort = null; 设置查询的默认排序
protected $defaultLimit = 25; 未指定时一次显示的项目数。（0 = maximumLimit）
protected $maximumLimit = 0; 可以通过 $_GET['limit'] 设置的最大限制 —— 这与 defaultLimit 有关，如果想要禁用分页，两者都应为 0。）将允许在单个调用中返回所有记录。
protected $unguard = false; 在创建/更新之前是否需要取消模型保护？

作用域

软删除记录

将 Phpsa\LaravelApiController\Model\Scopes\WithSoftDeletes 特性添加到您的模型中，添加到资源文件中

class MyModelResource extends ApiResource
{

 protected static $allowedScopes = [
        'withTrashed',
        'onlyTrashed'
    ];

现在可以为查询附加 withTrashed=1 或 onlyTrashed=1。

响应

可以通过覆盖以下受保护的方来覆盖每个点的响应

handleIndexResponse
handleStoreResponse
handleShowResponse
handleUpdateResponse
handleDestroyResponse

安全

如果您发现任何与安全相关的问题，请通过电子邮件而不是使用问题跟踪器。

鸣谢

赞助商

Custom D

camilord / laravel-api-controller

维护者

详细信息