README

laravel-api-resource 包简化了在 Laravel 应用程序中处理 JSON 响应的过程。它提供了一种简单的方法来创建一致和标准化的 API 资源，同时利用 Laravel 内置的资源类并遵守 JSON 规范。此包帮助开发者高效地管理资源转换、处理关系和自定义资源属性，确保 API 开发流程的简洁和可维护性。无论您是构建新的 API 还是维护现有的 API，laravel-api-resource 都可以增强您以最小努力提供强大且符合规范的 JSON 响应的能力。

安装

composer require singlequote/laravel-api-resource

发布文件

发布配置

php artisan vendor:publish --tag=laravel-api-resource-config

发布存根文件

php artisan vendor:publish --tag=laravel-api-resource-stubs

API 资源生成

php artisan make:api-resource {model}

使用上述命令，您可以生成一组完整的 API 资源，包括 API 控制器、操作、请求和 API 资源。

例如，如果我们想为我们的 User 模型生成一个 API 资源。

php artisan make:api-resource User

以下文件将被创建

App/Http/Controllers
    - ApiUserController

App/Actions/Users
    - DeleteUserAction
    - IndexUsersAction
    - ShowUserAction
    - StoreUserAction
    - UpdateUserAction

App/Http/Requests/Users
    - IndexUserRequest
    - ShowUserRequest
    - StoreUserRequest
    - UpdateUserRequest

App/Http/Resources
    - UserResource

生成完成后，您可以将您的 API 资源路由添加到 api.php 路由文件中。

/*
  |--------------------------------------------------------------------------
  | User routes
  |--------------------------------------------------------------------------
 */
Route::apiResource('users', UserController::class)->only('index', 'store', 'show', 'update', 'destroy');

资源方法

该包提供默认方法，可用于快速设置您的 API。例如，策略服务可以用于向资源响应添加策略。

   use SingleQuote\LaravelApiResource\Service\ApiPolicyService;

    public function toArray(Request $request): array
    {
        return [
            // ...
            'policies' => ApiPolicyService::defaults($this->resource),
        ];
    }

此外，您还可以将额外的策略方法作为第二个参数传递。

'policies' => ApiPolicyService::defaults($this->resource, ['sendInvite', 'acceptInvite']),

API 方法

该包提供默认的 API 选项。要使用提供的辅助函数，请将 HasApi 特性添加到您的模型中。在下面的代码示例中，我们使用名为 Ziggy 的包来解析 URL。如果您不使用任何 JavaScript 库来构建您的 URL，则必须根据以下示例手动构建 URL。例如

axios.get(route('api.users.index', {
	limit : 100
}))

将看起来像

GET: <your_site_url>/api/users?limit=100

limit 包提供的默认每页结果数设置为 1000。您可以在 laravel-api-resource 配置文件中更改默认值。要更改单个请求的限制，可以使用 limit 辅助函数。

axios.get(route('api.users.index', {
    limit : 100
}))

search 如果您想创建搜索输入，则可以使用搜索辅助函数。搜索字段接受一个包含两个字段的数组：字段和查询。字段是 API 应该搜索的列。查询是用于在列中搜索的查询。

axios.get(route('api.users.index', {
	search: {
        fields: ['name', 'email'],
        query: "john"
    }
}))

如果您想搜索模型中的所有可填充列，可以使用通配符 * 作为搜索字段

axios.get(route('api.users.index', {
	search: {
        fields: ['*'], // search in all fillable columns
        query: "john"
    }
}))

where 您可以使用查询构建器的 where 方法向查询添加 "where" 条件。调用 where 方法的最基本调用需要两个参数。第一个参数是列的名称。第二个参数是要与列的值进行比较的值。

axios.get(route('api.users.index', {
     where: {
        first_name: "john"
    }
}))

您还可以传递额外的运算符来检索数据，例如，获取所有日期早于某个日期的用户

axios.get(route('api.users.index', {
     where: {
        date_of_birth: {
           gt: "1995-01-31"
        } 
    }
}))

** 可用运算符 **

whereIn whereIn 方法验证给定列的值是否包含在给定的数组中

axios.get(route('api.users.index', {
	whereIn: {
        role: ['admin', 'employee']
    }
}))

whereNotIn whereNotIn 方法验证给定列的值是否不包含在给定的数组中

axios.get(route('api.users.index', {
	whereNotIn: {
        role: ['quests', 'visitors']
    }
}))

whereNotNull whereNotNull 方法验证给定列的值不是 NULL

axios.get(route('api.users.index', {
    whereNotNull: "password"
}))

has 当检索模型记录时，您可能希望根据关系的存在来限制您的结果。例如，假设您想检索所有至少有一个角色的用户。

axios.get(route('api.users.index', {
    has:  ['roles']
}))

doesntHave 在检索模型记录时，您可能希望根据关系的存在来限制结果。例如，假设您想要检索没有任何角色附加的所有用户。

axios.get(route('api.users.index', {
    doesntHave:  ['roles']
}))

whereRelation 如果您想要查询与关系的存在性，并且仅附加一个简单的where条件到关系查询上。

axios.get(route('api.users.index', {
    whereRelation:  {
        roles: {
            name: 'admin',
        }
    }
}))

您还可以传递一个额外的运算符来检索数据，例如，获取所有角色创建日期在某个日期之后的用户。

axios.get(route('api.users.index', {
    whereRelation:  {
        roles: {
            created_at: {
                gt: "2024-01-01",
            },
        }
    }
}))

with 有时您可能需要预加载多个不同的关系。要做到这一点，只需将关系数组传递给with方法即可。

axios.get(route('api.users.index', {
    with: ['roles']
}))

使用with与深度 当您想要检索包含其他关系的关系时，您可以在每个模型上设置一个属性。这允许您允许某些模型接受多个深度。将属性$apiRelations添加到您的模型中。

class User extends Authenticatable
{
    public array $apiRelations = [
        'roles.permissions', //allows for users.roles.permissions
    ];

select 有时您可能只需要资源中的几个列，并保持API响应的大小。

axios.get(route('api.users.index', {
    select: ['id', 'name']
}))

orderBy/orderByDesc 有时您可能想要更改API响应的排序。您可以使用orderBy或orderByDesc助手。

axios.get(route('api.users.index', {
    orderBy: 'name'
}))

自定义可排序列 当使用例如在模型查询中使用withCount或withSum时，默认情况下该列不可排序，因为它不存在于您的可填充属性中。要使自定义列可排序，您可以将$apiOrderBy属性添加到您的模型中，以使这些列可排序。

例如，要使文章价格可排序，请将withSum添加到您的查询中。

$query->withSum('articles', 'price');

class Product extends Model
{
    /**
     * @var array
     */
    public array $apiOrderBy = [
        'articles_sum_price',
    ];

然后，将orderBy添加到您的API请求中。

.../products?orderBy=articles_sum_price

贡献

有关详细信息，请参阅贡献指南。

Postcardware

您可以使用此包，但如果它进入您的生产环境，我们非常感谢您从您的家乡给我们寄一张明信片，并说明您正在使用哪些包。

我们的地址是：Quotec，Traktieweg 8c 8304 BA，Emmeloord，荷兰。

致谢

许可

MIT许可（MIT）。有关更多信息，请参阅许可文件。

singlequote / laravel-api-resource

维护者

详情