README

这是一个为 Laravel 提供工具集合的包，用于简化 Laravel 开发，这个包包含了来自 Spatie（最佳 Laravel 包开发者！）的外部包。

这个包提供了上述包的辅助函数和类，简化了它们的用法，或者简单地说，这就是我喜欢使用包的方式。不仅如此，我还编译了我自己在大多数项目中经常使用的类。

这个包可以帮助你

使用 spatie 的 laravel-query-builder 过滤查询
简单使用 spatie 的 media-library 添加单个媒体（通常情况下，是的，我在谈论个人头像）
生成和验证 OTP
同步所有角色及其权限
生成 CRUD 文件，附带其功能！
等等！

内容

安装
过滤查询
生成和验证 OTP
单媒体
同步角色和权限
生成 CRUD 文件
生成动作
生成枚举
生成查询

安装

使用 composer 依赖管理器安装 peddos-laravel-tools

composer require dwikipeddos/peddos-laravel-tools

别忘了运行以下命令发布配置文件

php artisan vendor:publish --tag=peddos-laravel-tools-config

还要发布 spatie 权限配置和迁移

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

使用示例

以下是一些包的使用示例

⚠️警告！⚠️

命令可能会在未来改变，因为这个包是从许多项目中编译而来的，因此命令名称和内容可能不一致。所以...请务必阅读使用示例，因为我将尽快更新文档。

过滤查询

通常，当使用 spatie 的 laravel-query-builder 时，你可以这样使用：

use Spatie\QueryBuilder\QueryBuilder;

QueryBuilder::for(Model::class)
    ->allowedFilters('name')
    ->get();

这是很好...直到你需要更多的过滤可能性，然后添加排序和包括，这可以快速使控制器变得混乱，所以我们可以将查询部分移动到单独的类中，你可以通过创建一个扩展 Dwikipeddos\PeddosLaravelTools\Queries\PaginatedQuery 的新类来实现这一点，我通常创建一个名为 Queries 的文件夹并将所有的查询类放在那里。

现在你只需要填写过滤条件和它将查询哪个模型，如下所示：

use Dwikipeddos\PeddosLaravelTools\Queries\PaginatedQuery;

class UserQuery extends PaginatedQuery
{
    //you have to override the __construct method
    public function __construct()
    {
        parent::__construct(User::query()); //which model to be queried for
    }

    //set filters that are allowed like you usually do when using spatie query builder
    protected function getAllowedFilters(): array
    {
        return [
            AllowedFilter::partial('name'),
            AllowedFilter::partial('email'),
        ];
    }

    //set sorts that are allowed like you usually do when using spatie query builder
    protected function getAllowedSorts(): array
    {
        return [
            AllowedSort::field('created_at'),
            AllowedSort::field('name'),
        ];
    }

    //set includes that are allowed like you usually do when using spatie query builder
    protected function getAllowedIncludes(): array
    {
        return [
            AllowedInclude::relationship('socialAccounts'),
            AllowedInclude::relationship('fcm_token'),
        ];
    }
}

我们还添加了 append，以便 API 消费者可以附加一些隐藏的属性。你只需要做的是添加：

//specify the attributes that can be appended
protected array $append = [
    'phone',
    'employer',
];

现在在你的控制器中你可以这样做：

function index(UserQuery $query){
    return $query->includes() //to apply includes
    ->sort() //to apply sorts
    ->filter() //to apply filter
}

//or you could simplify it even more with
function index(UserQuery $query){
    return $query->filterSortPaginateWithAppend();
}

paginate？函数说 paginate 吗？是的，它确实说了，我们还添加了页面限制到我们的查询类中，你可以通过添加 limit 查询来使用它。最后，你现在可以像在 laravel-query-builder 中一样进行过滤。

/user?filter[name]=peddos&sort=name&append[]=phone&limit=10

这将过滤名为 peddos 的用户，按 name 排序，并附加 phone，单页将只包含 10 个用户。

成功了！

生成和验证 OTP

要生成 OTP，包使用 Action 类，这是一个处理单个函数的类，生成 OTP 如同阅读更多关于动作的信息一样简单，你可能想阅读生成动作

use Dwikipeddos\PeddosLaravelTools\Actions\GenerateOTPAction;

(new GenerateOTPAction)->execute(
    4, //number of seed
    1, //user_id
);

或者你可以将动作注入到控制器中

function login(LoginRequest $request, GenerateOTPAction $action){
    //login stuff
    $action->execute(4,1);
}

⚠️限制⚠️

此操作仅适用于Laravel默认的用户模型，虽然你现在可以发布迁移，但你只能添加一些列而不改变现有的列，因为这样做可能会破坏此操作。

单媒体

单个媒体是一个工具，用于使用Spatie\laravel-medialibrary将您的模型与单个媒体关联。通常，要从模型中加载单个媒体，您需要这样做：

$article->getFirstMedia()->getUrl();

要将内容存储到媒体集合中，您可以这样做：

$article->addMediaFromRequest("image")->toMediaCollection("image");

现在，使用这个包，这变得简单得多。首先，您需要像这样准备您的模型：

use Dwikipeddos\PeddosLaravel\Tools\HasSingleImage;
use Spatie\MediaLibrary\HasMedia;

class Article implements HasMedia{
    use HasSingleImage;
}

默认情况下，该包应该使用“image”和“thumb”分别作为“image”和“thumbnail”的集合名称来生成图像和缩略图，但是您可以通过覆盖$defaultSingleImageName和$defaultThumbnailName来更改这一点，如下所示：

class Article implements HasMedia{
    use HasSingleImage;

    $defaultThumnailName = "thumbnail";
    $defaultSingleImageName = "Banner";
}

默认情况下，该包包含图像占位符，以防模型没有任何图像，您可以通过以下方式更改默认设置：

public string $defaultSingleImage = "https://image.com/pepega.png";
public string $defaultThumbnail = "https://image.com/pepega-sm.png";

那么，如何使用单个图像插入图像呢？只需这样做：

class ArticleController extends Controller{
    function store(ArticleStoreRequest $request){
        $article = Article::create($request->validated());
        $article->addSingleImageFromRequest(); //THIS!
    }
}

默认情况下，addSingleImageFromRequest()将使用模型中的$defaultSingleImageName作为包含图像的请求键，但是您也可以这样做：

    $article->addSingleImageFromRequest("my_image_key"); 
    //this will make the package to use "my_image_key" to find the image

要获取图像，您可以简单地这样做：

$article->getSingleImage();
//or to get the thumbnail
$article->getSingleImageThumbnail();

成功了！

同步角色和权限

此包可以帮助您同步角色和权限，而且相当简单。首先，如果您还没有发布配置文件，请运行以下命令以发布它：

php artisan vendor:publish --tag=peddos-laravel-tools-config

对了，别忘了运行迁移

php artisan migrate

现在，您的配置目录中应该有一个名为peddoslaraveltools.php的文件。现在您只需在available_permissions数组中编写允许访问的权限和角色即可，配置文件应如下所示：

'available_permissions' => [
    [
        'name' => 'post.create', //permission name
        'roles' => ['super-admin', 'user'] // role that are allowed to access said permission
    ],
    [
        'name' => 'post.view',
        'roles' => ['user','guest','super-admin']
    ]
],

完成此操作后，您现在可以使用命令同步权限和角色：

php artisan peddos-permission-role:sync

此命令将在数据库中尚未创建权限和角色的情况下创建它们，因此您不必担心这一点！

生成 CRUD 文件

您知道创建基本CRUD文件时的那种无聊感吗？从模型、迁移、工厂、控制器、路由、请求和策略？几乎一切都相同，只是模型处理不同，对吧？那么，每次创建简单CRUD时，您真的需要每次都键入它们吗？现在，您可以使用此包的CRUD生成器完全跳过所有这些！只需运行以下命令：

php artisan generate:all {Name}

将{Name}替换为您要创建的模型名称，然后一切就绪！基本的CRUD已经工作，过滤也已经应用！

⚠️限制⚠️

目前，此命令只能生成基本CRUD，无法生成更复杂的功能，您仍然需要在迁移、工厂、查询和FormRequest中的验证规则中填写。

生成动作

Actions：Actions是一个简单的类，可以注入并仅包含一个简单的函数，这对于将一些简单的函数从控制器中卸载很有用。要生成此Action，您只需这样做：

php artisan make:action {name}

将{name}替换为操作名称，通常它应该是动词，如“VerifyUserOTP”。如果您查看在App\Actions\{Name}中生成的文件，您应该看到如下内容：

namespace App\Actions;

class VerifyOtpAction
{
    public function execute(string $otp): bool
    {
       //some code
    }
}

如您所见，Actions只有一个函数，即execute，此函数可能需要也可能不需要参数，因为这就像服务类但更简单。您可以在控制器中使用Action类，如下所示：

class AuthController{
    function verifyOtp(Request $request, VerifyOtpAction $action){
        //you can use it like this
        $isOtpValid = $action->execute($request->otp);
    }
}

或者您可以手动创建它并像这样使用：

$isOtpValid = (new VerifyOtpAction)->execute($otp);

总之，Actions就像服务类一样，非常简单，只需要一个函数（execute），但您可能需要在多个地方使用它，因此您需要为它创建一个新的类。

生成枚举

PHP 8 支持枚举类型，我非常喜欢它，以至于有点过度使用了😂。那么，什么是枚举呢？基本上，枚举就是一个定义了自定义类型的类，这个类型限制在几个离散的可能值中。例如，你想要在数据库中存储性别，最可能的方式是存储为一个单字符，用 M 和 F 分别代表男性和女性。但如果你想做类似的事情，但是使用不同的列表呢？例如，你想要创建一个“员工如何上班”的列表，你不想将其存储为字符串，因为随着应用规模的扩大，这会占用很多存储空间。你可以将可能的答案转换为数字，然后在需要的时候再将它们转换回字符串，例如

步行 = 1
驾车 = 2
公共交通 = 3

然后你可以在数据库中用一个整型列来存储它，这样就节省了空间。此外，如果你想要添加新的可能答案，你只需要为新答案分配一个数字，然后搞定。

一个典型的 PHP 枚举应该看起来像这样

namespace App\Enums;

enum EmployeeAccomodation: int
{
    case WALKING = 1;
    case DRIVING = 2;
    case PUBLIC_TRANSPORTATION = 3;
}

要使用这个包创建一个枚举，你可以使用以下命令

php artisan make:enum {name}

将 {name} 替换为你的枚举名称，这将在一个名为 App\Enums 的目录下创建一个新的文件。我知道这只是一个简单的类，可能不需要为它创建命令，但嘿，我比较懒，所以这里有一个。在 Laravel 中，要将数字转换为相应的枚举，你可以这样做

EmployeeAccomodation::from(1); //WALKING

你也可以用枚举做一些类似的事情

namespace App\Enums;

enum EmployeeAccomodation: int
{
    case WALKING = 1;
    case DRIVING = 2;
    case PUBLIC_TRANSPORTATION = 3;

    function toString(){
        return Str::title(Str::replace('_', ' ', Str::snake($this->name)));
    }

    //
    EmployeeAccomodation::from(3)->toString(); //Public Transportation
}

成功了！

生成查询

查询类是这个包中最强大的工具之一。通常，查询是自动由 php artisan generate:all {name} 生成的，但如果你没有使用它，并想创建一个查询，你可以使用这个命令来生成查询

php artisan make:query {name}

将 {name} 替换为你的查询名称，它应该被创建在 App\Queries\ 目录下。至于如何使用这个查询，你可能需要阅读过滤查询

成功了！

许可协议

MIT

dwikipeddos / peddos-laravel-tools

维护者

详细信息

README

内容

安装

使用示例

过滤查询

生成和验证 OTP

单媒体

同步角色和权限

生成 CRUD 文件

生成动作

生成枚举

生成查询

许可协议