Laravel Process Approval

The package supports UUID primary keys and polymorphic relations. For fresh installs, it is recommended to use the process-approval:install command, which handles publishing migrations and updating the configuration automatically.

To install with UUID support:

php artisan process-approval:install --uuids

If you need to overwrite existing published files, add the --force flag:

php artisan process-approval:install --uuids --force

Note: If you choose to publish migrations manually using vendor:publish, you must set load_migrations to false in your process_approval.php config file to prevent duplicate migration attempts.

Auto-submitting models

By default, models require manual submission. To make a model automatically ready for approval upon creation, define the enableAutoSubmit() method in your model:

public function enableAutoSubmit(): bool
{
    return true;
}

Alternatively, set public bool $autoSubmit = true;.

Bypassing approval

To skip the approval process for a specific instance, implement:

public function bypassApprovalProcess(): bool
{
    return true;
}

To install the package, use Composer to add it to your Laravel project.

composer require ringlesoft/laravel-process-approval

To replace the default check/times icons with actual user signatures, implement getSignature() in your User model. It should return the URL/path to the signature image.

class User extends Model 
{
    public function getSignature()
    {
        return $this->signature_path;
    }
}

To enable approval workflows on a model, you must implement the ApprovableModel interface and use the Approvable trait.

You must also implement the onApprovalCompleted(ProcessApproval $approval): bool method. This method is called when the final approval in the sequence is granted. Return true to finalize the process or false to roll back the last approval.

use RingleSoft\LaravelProcessApproval\Interfaces\ApprovableModel;
use RingleSoft\LaravelProcessApproval\Traits\Approvable;
use RingleSoft\LaravelProcessApproval\Models\ProcessApproval;

class FundRequest extends Model implements ApprovableModel
{
    use Approvable;

    public function onApprovalCompleted(ProcessApproval $approval): bool
    {
        // Logic to execute when the entire process is finished
        return true;
    }
}

You can interrupt the approval workflow by implementing pauseApprovals() in your model:

• Return true: The approval actions UI disappears entirely. Use this to perform custom logic before allowing approvals to resume.
• Return 'ONLY_ACTIONS': The existing approvals are displayed, but the action buttons (approve/reject) are hidden and disabled.

public function pauseApprovals()
{
    // Return true to hide UI, or 'ONLY_ACTIONS' to disable buttons
    return true;
}

The package supports multi-tenancy by allowing different approval flows for different tenants.

1. Ensure your users table has a tenant identifier column (e.g., tenant_id).
2. Configure the multi_tenancy_field option in the package configuration to match your column name.
3. When a user is logged in, the package uses their tenant_id value to filter and apply the correct approval steps.

Use the process-approval:install command to initialize the package. This command publishes the configuration file, copies the necessary database migrations to your database/migrations directory, and updates your config/process_approval.php file.

UUID Support

If your application uses UUIDs for primary keys (specifically for users, roles, and your approvable models), you should use the --uuids flag. If you do not provide this flag, the command will prompt you to confirm whether you want to use UUIDs.

php artisan process-approval:install

# To use UUIDs for primary keys:
php artisan process-approval:install --uuids

# To overwrite existing configuration and migrations:
php artisan process-approval:install --force

To show a visual summary of the approval status (using check, times, or exclamation icons) in lists, use the <x-ringlesoft-approval-status-summary> component.

<x-ringlesoft-approval-status-summary />