README

prismaticoder/maker-checker-laravel 包是一个全面的Laravel包，它为您的应用程序提供灵活可定制的制作人-检查人系统。它允许您实现应用程序中各种操作的审批工作流程，例如创建、更新和删除记录。它还允许您执行随机操作。使用此包，您可以在最终确定之前确保重要操作经过审批过程。

特性

• 制作人-检查人系统：为应用程序中的关键操作实现审批工作流程，确保在最终确定之前对更改进行审查和批准。
• 灵活配置：根据应用程序的具体需求自定义制作人-检查人设置。定义允许进行制作/检查请求的模型、请求被视为过期的时间等。
• 事件驱动：该包在审批工作流程中触发事件，允许您挂钩到这些事件并执行自定义操作或集成。
• 日志和审计：跟踪和记录审批过程，包括谁创建了请求、谁批准了它以及何时。深入了解操作和审批的历史。

要求

• PHP 8 或更高版本
• Laravel 8 或更高版本

Maker-Checker Laravel包需要PHP版本8或更高版本和Laravel版本8或更高版本才能正常运行。在安装包之前，请确保您的开发环境满足这些要求。

您可以在终端中运行以下命令来检查您的PHP版本：

php -v

安装

您可以通过Composer安装 prismaticoder/maker-checker-laravel 包。在终端中运行以下命令：

composer require prismaticoder/maker-checker-laravel

配置

安装包后，您需要发布配置和迁移文件以自定义制作人-检查人设置。运行以下命令：

迁移

php artisan vendor:publish --provider="Prismaticoder\MakerChecker\MakerCheckerServiceProvider" --tag="makerchecker-migration"

配置

php artisan vendor:publish --provider="Prismaticoder\MakerChecker\MakerCheckerServiceProvider" --tag="makerchecker-config"

这将创建一个 config/makerchecker.php 文件在您的应用程序的配置以及一个 create_maker_checker_requests_table 迁移文件在您的 database/migrations 文件夹。

用法

检索请求

该包公开了一个 MakerCheckerRequest 模型，它可以像其他Laravel模型一样查询。

use Prismaticoder\MakerChecker\Models\MakerCheckerRequest

MakerCheckerRequest::all(); // Get all requests
MakerCheckerRequest::status('pending')->get(); // Get all pending requests

$request = MakerCheckerRequest::first();

$request->status; // the status of the request: pending | approved | rejected | failed | expired
$request->type; // the request type: create | update | delete | execute
$request->description; // the description provided for the request
$request->payload; // the payload passed when the request was initiated
$request->maker; // the request maker
$request->checker; // the request checker
$request->subject; // the subject on which the request is to be executed on (null for execute requests)
$request->made_at; // timestamp of when the request was made.
$request->checked_at; // timestamp of when the request was checked.
$request->remarks; // remarks added by the checker when checking.
$request->exception; // exception encountered in the event that the request failed during approval.

启动新的请求

启动新请求的一种方法是通过使用 MakerChecker Facade 类。以下是一个创建用户请求的示例：

use App\Models\User;
use Primaticode\MakerChecker\Facades\MakerChecker;

//CREATE A USER
MakerChecker::request()
    ->toCreate(User::class, ['name' => 'Tobi David', 'email' => 'johndoe@example.com'])
    ->madeBy(auth()->user())
    ->save();

//UPDATE A USER
MakerChecker::request()
    ->toUpdate($user, ['name' => 'Tommy Ify'])
    ->madeBy(auth()->user())
    ->save()

//DELETE A USER
MakerChecker::request()
    ->toDelete($user)
    ->madeBy(auth()->user())
    ->save()

或者，您可以选择在制作人模型中包含 MakesRequests 特性。

use Illuminate\Database\Eloquent\Model;
use Prismaticoder\MakerChecker\Traits\MakesRequests;

class User extends Model
{
    use MakesRequests;

    ...
}

包含后，上述请求现在可以按照以下格式构建：

use App\Models\User;

//CREATE A USER
auth()->user()
    ->requestToCreate(User::class, ['name' => 'Tobi David', 'email' => 'johndoe@example.com'])
    ->save();

//UPDATE A USER
auth()->user()
    ->requestToUpdate($user, ['name' => 'Tommy Ify'])
    ->save()

//DELETE A USER
auth()->user()
    ->requestToDelete($user)
    ->save()

您还可以使用 description() 方法给请求添加自定义描述。

auth()->user()
    ->requestToCreate(User::class, ['name' => 'Tobi David', 'email' => 'johndoe@example.com'])
    ->description('Invitation of Tobi David as a collaborator.')
    ->save();

可执行请求类型

除了创建、更新和删除模型的通用操作外，还可能需要执行不属于这些类别的杂项请求，例如向外部系统发出http调用、组合不同的操作等。因此，引入了可执行请求的概念。

要启动一个新的可执行请求，首先需要创建一个扩展 Primaticode\MakerChecker\Contracts\ExecutableRequest 协议的可执行请求类。

use Illuminate\Support\Facades\Http;
use Prismaticoder\MakerChecker\Contracts\ExecutableRequest;
use Prismaticoder\MakerChecker\Contracts\MakerCheckerRequestInterface;

class InitiatePayment extends ExecutableRequest
{
    public function execute(MakerCheckerRequestInterface $request)
    {
        Http::post('payment-service.com/pay', $request->payload);
    }
}

在这里，我们有一个可执行请求，当批准时执行一些基本操作：根据请求有效负载中的参数促进支付。

要启动执行此请求的请求，我们使用 requestToExecute() 方法。

use App\Executables\InitiatePayment;

auth()->user()
    ->requestToExecute(InitiatePayment::class, ['amount' => '500', 'currency' => 'NGN', 'to_account' => 'john@example.com'])
    ->save();

当这个请求被批准时，将调用可执行类的 execute() 方法来促进指定的操作。

使用 tap() 自定义请求

请求构建器提供了一个 tap() 方法，允许您通过应用操作或修改来自定义底层请求对象。tap() 方法接受一个闭包函数作为其参数，您可以在其中对请求执行各种操作。

以下是一个示例

auth()->user()
    ->requestToCreate(User::class, ['name' => 'Tobi David', 'email' => 'johndoe@example.com'])
    ->tap(function ($request) {
        // Perform customizations on the request
        $request->custom_field = $customValue
    })
    ->save();

在上面的示例中，tap() 方法用于通过设置存储请求的表中的自定义字段值来自定义请求。

请注意，tap() 方法是可选的，可以在需要在对请求进行初始化之前执行额外操作或修改时使用。

通过利用 tap() 方法，您可以灵活地根据特定要求自定义请求对象，确保它捕获了所有必要的详细信息，以供制作检查过程使用。

批准/拒绝请求

要批准或拒绝制作检查请求，您也可以使用 MakerChecker 门面。以下是一个批准请求的示例

use Primaticode\MakerChecker\Facades\MakerChecker;

MakerChecker::approve($request, auth()->user(), $reason);

在上面的示例中，我们使用 MakerChecker 门面的 approve() 方法来批准请求。我们传递请求模型的实例以及批准请求的用户。

同样，您可以使用 reject() 方法来拒绝请求

use Primaticode\MakerChecker\Facades\MakerChecker;

MakerChecker::approve($request, auth()->user()), $reason;

类似于 MakesRequests 特性，此包还提供了一个可以包含在检查模型中的 ChecksRequests 特性。

use Illuminate\Database\Eloquent\Model;
use Prismaticoder\MakerChecker\Traits\ChecksRequests;

class Admin extends Model
{
    use ChecksRequests;

    ...
}

完成以上操作后，批准和拒绝现在可以像这样显示

use Primaticode\MakerChecker\Facades\MakerChecker;

//Approve a request
auth()->user()->approve($request, $reason);

//Reject a request
auth()->user()->reject($request, $reason);

事件监听器和用户定义的回调

Maker-Checker 包在请求生命周期的不同阶段触发事件，允许您监听这些事件并在需要时执行额外操作。除了事件监听器外，您还可以在启动请求时传递用户定义的回调，以指定在请求批准或拒绝后/前要执行的操作。

监听事件

您可以通过在应用程序中注册事件监听器来监听 Maker-Checker 事件。以下是如何监听包提供的事件的示例

use Primaticode\MakerChecker\Events\RequestApproved;
use Primaticode\MakerChecker\Events\RequestFailed;
use Primaticode\MakerChecker\Events\RequestInitiated;
use Primaticode\MakerChecker\Events\RequestRejected;

Event::listen(RequestApproved::class, function (RequestApproved $event) {
    $request = $event->request; // Get the request instance
    // Perform additional actions based on the approved request
});

Event::listen(RequestRejected::class, function (RequestRejected $event) {
    $request = $event->request; // Get the request instance
    // Perform additional actions based on the rejected request
});

Event::listen(RequestInitiated::class, function (RequestInitiated $event) {
    $request = $event->request; // Get the request instance
    // Perform additional actions based on the initiated request
});

Event::listen(RequestFailed::class, function (RequestFailed $event) {
    $request = $event->request; // Get the request instance
    $exception = $event->exception; //Get the exception encountered
    // Perform additional actions based on the failed request
});

在上面的示例中，我们使用 Event::listen() 方法注册了一个监听器，用于监听包公开的四个事件。事件监听器接收事件的一个实例，然后可以执行请求操作，该请求作为事件传入。

用户定义的回调

在启动 Maker-Checker 请求时，您还可以传递用户定义的回调来指定在请求批准或拒绝后/前要执行的操作。以下是如何使用用户定义的回调的示例

use App\Models\User;
use Primaticode\MakerChecker\Models\MakerCheckerRequest;
use Throwable

auth()->user()
    ->requestToCreate(User::class, ['name' => 'Tobi David'])
    ->beforeApproval(function (MakerCheckerRequest $request) {
        // Perform actions before the request is approved (if this action fails, the request is marked as failed)
    })
    ->beforeRejection(function (MakerCheckerRequest $request) {
        // Perform actions before the request is rejected (if this action fails, the request is marked as failed)
    })
    ->afterApproval(function (MakerCheckerRequest $request) {
        // Perform actions after the request is approved
    })
    ->afterRejection(function (MakerCheckerRequest $request) {
        // Perform actions after the request is rejected
    })
    ->onFailure(function (MakerCheckerRequest $request, Throwable $exception) {
        // Perform action when the request fails
    })
    ->save();

这五种不同的方法可以链接起来，以确定在请求生命周期中的不同事件期间要执行的操作。

就是这样！您现在已经拥有了事件监听器和用户定义的回调，可以在 Laravel 应用程序中扩展 Maker-Checker 包的功能。

致谢

此包借鉴了 Spatie 的优秀 spatie/laravel-activitylog 包的一些灵感。我感谢他们为开发 Laravel 生态系统所做的持续工作。

贡献

我乐意接受社区的贡献来增强和改进此包。请随意在此处提交错误报告、功能请求或拉取请求。

许可证

prismaticoder/maker-checker-laravel 包是开源软件，根据 MIT 许可证授权。请参阅 LICENSE 文件以获取更多信息。