Maker Checker Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require moffhub/maker-checker
   php artisan vendor:publish --tag=maker-checker-migrations
   php artisan migrate
   php artisan vendor:publish --tag=maker-checker-config
   

2. Implement User Contract: Add MakerCheckerUserContract to your User model:

   use Moffhub\MakerChecker\Contracts\MakerCheckerUserContract;
   
   class User extends Authenticatable implements MakerCheckerUserContract
   {
       public function hasMakerCheckerPermission(string $permission): bool { ... }
       public function getMakerCheckerTeamId(): ?int { ... }
       public function getMakerCheckerRole(): ?string { ... }
       public function getMakerCheckerEmail(): ?string { ... }
   }
   

3. First Use Case: Add the RequiresApproval trait to a model (e.g., Post):

   use Moffhub\MakerChecker\Traits\RequiresApproval;
   
   class Post extends Model
   {
       use RequiresApproval;
       protected static array $approvalRequirements = ['create' => ['editor' => 1]];
   }
   

   Now, creating a Post will trigger an approval workflow.

Implementation Patterns

Workflows

1. Auto-Intercept Workflow:

   • Add RequiresApproval trait to models.
   • Define $approvalRequirements (e.g., ['create' => ['admin' => 2]]).
   • Use createWithoutApproval() or withoutApprovalDo() for bypasses.

2. Facade-Based Workflow:

   • Use MakerChecker::create(), update(), or delete() for manual requests.
   • Example:

     $request = MakerChecker::create(Post::class, ['title' => 'Draft'], 'Draft post');
     

3. Request Builder Pattern:

   • Chain methods for full control:

     $request = MakerChecker::request()
         ->toCreate(Post::class, ['title' => 'Post'])
         ->withApprovals(['editor' => 1])
         ->beforeApproval(fn($r) => Log::info('Pre-approval'))
         ->save();
     

Integration Tips

• API Integration: Use REST endpoints (/maker-checker/requests) for frontend approval flows.
• Event Listeners: Hook into MakerCheckerRequestApproved or MakerCheckerRequestRejected events.
• Custom Actions: Extend ExecutableRequest for non-CRUD operations (e.g., fund transfers).

Gotchas and Tips

Pitfalls

1. Race Conditions:

   • Use pessimistic_locking in config to prevent double-approvals.
   • Example config:

     'locking' => [
         'enabled' => true,
         'timeout' => 30, // seconds
     ],
     

2. User-Specific Approvals:

   • Validate user existence unless explicitly disabled (validateExistence: false).
   • Example error:

     try {
         $request->requiringUsersToApprove(['nonexistent@example.com']);
     } catch (RequestCouldNotBeInitiated $e) {
         // Handle missing user
     }
     

3. Approval Expiry:

   • Set expiry_minutes in config to auto-expire pending requests:

     'request_expiry' => [
         'enabled' => true,
         'minutes' => 1440, // 24 hours
     ],
     

Debugging

• Audit Trail: Export logs via /maker-checker/audit/export.
• Request Status: Check $request->status (e.g., pending, approved, rejected).
• Pending Approvals: Use $request->getPendingRoles() or $request->getPendingUsers().

Extension Points

1. Custom Rules Engine:

   • Override MakerChecker::getApprovalRequirements() to dynamically set rules.
   • Example:

     MakerChecker::extend(function ($request) {
         if ($request->payload['amount'] > 50000) {
             return ['finance' => 2];
         }
         return ['manager' => 1];
     });
     

2. Notifications:

   • Extend MakerCheckerNotification to customize email templates or add Slack alerts.

3. Delegation:

   • Use MakerChecker::delegateApproval($request, $delegateUser, $expiryMinutes) for temporary approval transfers.

Config Quirks

• Database-Driven Config: Override default rules via maker_checker_config table.
• Multi-Tenancy: Set getMakerCheckerTeamId() in the User contract to scope requests by team.