README

Laravel Magic提供抽象控制器、模型、通用请求、特性、异常和各种中间件，以便从零开始轻松快速地生成API资源。

支持我们

Laravel Magic是一个免费开源项目。如果您使用该项目，请在Github上给我们加星标...这不需要任何代价，只需点击一下！😉

安装

您可以通过composer安装此包

composer require dominiquevienne/laravel-magic

此包不提供

任何迁移
任何配置文件
任何视图

需要设置的ENV变量

# Duration of the cache handled by the package
LARAVEL_MAGIC_CACHE_DEFAULT_DURATION=3600
# Used to ensure that queries handled by the AbstractController will use a Filters/ModelFilter.php class
LARAVEL_MAGIC_FILTER_MODE=paranoid
# Public key used to validate JWT tokens
OAUTH_KEY_PUB=myPublicKey
# Acceptable delay in seconds between two servers (used for tokens validation)
JWT_LEEWAY=300

使用方法

模型

从AbstractModel扩展您的模型将为您提供在IDE中使用PHPDoc获取自动完成的机会，并可以检查给定模型是否存在关系。

它还将使AbstractController能够实现魔法。（见控制器）

<?php

namespace App\Models;

use Dominiquevienne\LaravelMagic\Models\AbstractModel;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;

/**
 * @property-read int $id
 * Your PHPDoc goes here 
 */
class YourModel extends AbstractModel
{
    use HasFactory;

    protected $fillable = [
    // ...
    ];
}

控制器

从AbstractController扩展您的控制器将为您提供一种完全自动化的方式来生成索引、显示、销毁、更新、存储方法，而无需编写任何控制器行。这将满足90%的API资源需求。

由于默认方法已经在AbstractController中可用，因此您可以直接配置路由以指向常用方法，魔法将自动发生。

<?php

namespace App\Http\Controllers;

use Dominiquevienne\LaravelMagic\Http\Controllers\AbstractController;

class YourController extends AbstractController
{
}

关系

当调用索引或显示端点时，您可以通过添加with GET参数来检索给定模型的直接关系。如果关系不可用，API不会抛出错误/警告。

如果属性未提供或经过清理后的值是空的，查询将生成一个不检索任何关系的正常查询。

字段

当调用索引或显示端点时，您可以添加fields GET参数以仅检索列出的字段。如果字段不可用，API不会抛出错误/警告。

如果属性未提供或经过清理后的值是空的，查询将抛出所有可用的字段。

过滤

当调用索引端点时，您可以添加filter GET参数以过滤列表，以便仅检索目标行。如果用于过滤的字段不可用，API不会抛出错误/警告。

如果属性未提供或经过清理后的值是空的，查询将生成一个检索所有行的正常查询。

排序

当调用索引端点时，您可以添加order GET参数以按所需的方式对提供的结果进行排序。

如果您提供一个不合规的字符串，API将抛出错误。

如果属性未提供，查询将生成一个不进行任何特定排序的检索所有行的正常查询。

分页

Laravel标准分页已集成。请参阅官方paginate 文档。

查询缓存

默认情况下，Laravel Magic 会缓存用于索引和显示方法的查询。它将使用它们的指纹来确保缓存值是对应于唯一查询的值。这种缓存方法考虑了应用程序内的过滤、用户过滤、字段、排序、关联和分页。

默认行为是将查询结果存储在缓存中8小时，但可以在你的 .env 文件中通过 LARAVEL_MAGIC_CACHE_DEFAULT_DURATION 变量来覆盖这个值。该变量的值是缓存的时间到秒。如果你想完全避免查询缓存，请使用 LARAVEL_MAGIC_CACHE_DEFAULT_DURATION=0。

请求

Laravel Magic 提供了一个 BootstrapRequest 文件，该文件将在任何 AbstractConctroller.create 和 AbstractConctroller.update 方法中被调用。如果你在 Requests 文件夹中有一个名为 ModelnameRequest 的请求，它将被用来生成验证规则。

过滤查询

在你的开发过程中，如果你创建了一个扩展 GenericFilter 类的 src/Http/Filters/ModelNameFilter.php 类，Laravel Magic 将自动过滤你在 CRUD 方法中检索数据的方式。如果没有创建此类，则默认不进行过滤。然而，如果你在 .env 文件中将 LARAVEL_MAGIC_FILTERING_MODE=paranoid 设置为，LaravelMagic 将使得获取任何数据变得不可能。

中间件

Laravel Magic 提供了 ForceJson 和 VerifyJwtToken 中间件。这些可以在 Laravel Kernel 中设置。

特质

我们还提供了 HasPublicationStatus、TimeStampsBy 和 SoftDeletesBy 特质。

HasPublicationStatus 特质

此特质将为你的模型添加一个发布状态并将其存储在数据库中。要使用此特质，将其添加到你的模型中，并迁移你的模式以具有 publication_status_id 字段。该字段的值由 $publicationStatusAvailable 属性处理。

TimeStampsBy 特质

此特质将为 creator 和 updater 关系添加，并将自动将用户 id 存储在 created_by 和 updated_by 表属性中。必须通过迁移添加这些属性。

SoftDeletesBy 特质

此特质将为 deleter 关系添加，并将自动将用户 id 存储在 deleted_by 表属性中。必须通过迁移添加这些属性。

异常

Laravel Magic 提供了这些异常

ControllerAutomationException
EnvException
PublicationStatusException
StatusUnknownException

这些是在内部使用的，但你当然也可以按需使用它们。

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的更多信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全漏洞

请参阅我们的安全策略了解如何报告安全漏洞。

致谢

许可

MIT 许可证（MIT）。请参阅许可文件了解更多信息。

dominiquevienne / laravel-magic

维护者

详细信息