{"id":31714633,"url":"https://github.com/aurorawebsoftware/aapproval","last_synced_at":"2025-10-09T01:42:21.654Z","repository":{"id":316035435,"uuid":"1061655426","full_name":"AuroraWebSoftware/AApproval","owner":"AuroraWebSoftware","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-22T09:01:25.000Z","size":1640,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-22T10:34:11.799Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AuroraWebSoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T08:00:30.000Z","updated_at":"2025-09-22T09:47:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"5aeee209-f11c-46f9-b3c1-16f718d46308","html_url":"https://github.com/AuroraWebSoftware/AApproval","commit_stats":null,"previous_names":["aurorawebsoftware/aapproval"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/AuroraWebSoftware/AApproval","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AuroraWebSoftware%2FAApproval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AuroraWebSoftware%2FAApproval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AuroraWebSoftware%2FAApproval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AuroraWebSoftware%2FAApproval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AuroraWebSoftware","download_url":"https://codeload.github.com/AuroraWebSoftware/AApproval/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AuroraWebSoftware%2FAApproval/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279000714,"owners_count":26082895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-09T01:42:17.454Z","updated_at":"2025-10-09T01:42:21.646Z","avatar_url":"https://github.com/AuroraWebSoftware.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AApproval - Laravel Approval Workflow Package\n![AApproval Package](assets/cover.png)\n![AApproval Package](assets/cover2.svg)\n![AApproval Package](assets/cover3.svg)\n\nAApproval provides a powerful and flexible approval workflow system for create/update/delete operations in Laravel applications. This package is backend-only and does not include any frontend components.\n\n## 🚀 Features\n\n- **Multi-Step Approval System**: Support for complex approval processes with multiple steps\n- **Flexible Approver Types**: Role, permission, and user-based approval mechanisms\n- **Trait-Based Integration**: Easily integrate with your existing models\n- **Automatic Workflow**: Automatically captures model operations and routes them to approval process\n- **Full Customization**: Define different approval flows for each model\n- **Laravel Authorization Integration**: Compatible with Laravel's existing authorization system\n\n## 📋 Requirements\n\n- PHP 8.1 or higher\n- Laravel 11.0 or higher\n- Spatie Laravel Permission package (recommended)\n\n## 📦 Installation\n\nInstall the package via Composer:\n\n```bash\ncomposer require aurorawebsoftware/aapproval\n```\n\nPublish the configuration file:\n\n```bash\nphp artisan vendor:publish --tag=aapproval-config\n```\n\nPublish migration files and run them:\n\n```bash\nphp artisan vendor:publish --tag=aapproval-migrations\nphp artisan migrate\n```\n\n## ⚙️ Configuration\n\nDefine approval flows for each model in `config/approvals.php`:\n\n```php\n\u003c?php\n\nreturn [\n    'flows' =\u003e [\n        'App\\\\Models\\\\Invoice' =\u003e [\n            [\n                'name' =\u003e 'Manager Approval', \n                'type' =\u003e 'role', \n                'identifier' =\u003e ['manager']\n            ],\n            [\n                'name' =\u003e 'Finance Approval', \n                'type' =\u003e 'role', \n                'identifier' =\u003e ['finance']\n            ],\n            [\n                'name' =\u003e 'GM Approval', \n                'type' =\u003e 'user', \n                'identifier' =\u003e [1] // User IDs\n            ],\n        ],\n        \n        'App\\\\Models\\\\PurchaseOrder' =\u003e [\n            [\n                'name' =\u003e 'Department Head Approval',\n                'type' =\u003e 'permission',\n                'identifier' =\u003e ['approve-purchase-orders']\n            ],\n        ],\n    ],\n    \n    // Permission name for direct approval bypass\n    'permission_name' =\u003e 'approval_direct',\n];\n```\n\n### Approver Types\n\n1. **Role Based**: `'type' =\u003e 'role'`\n    - Uses Spatie Laravel Permission package\n    - Specify role names in `identifier` array\n\n2. **Permission Based**: `'type' =\u003e 'permission'`\n    - Uses Spatie Laravel Permission package\n    - Specify permission names in `identifier` array\n\n3. **User Based**: `'type' =\u003e 'user'`\n    - For specific users\n    - Specify user IDs in `identifier` array\n\n### Direct Approval Permission\n\nYou can customize the permission name for bypassing approval workflow in the config file. Users with this permission can perform direct operations without going through approval process:\n\n```php\n'permission_name' =\u003e 'approval_direct', // or any custom permission name\n```\n\n## 🔧 Usage\n\n### Adding Trait to Model\n\nAdd the `HasApprovals` trait to the model you want to use the approval system with:\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Aurorawebsoftware\\AApproval\\Traits\\HasApprovals;\n\nclass Invoice extends Model\n{\n    use HasApprovals;\n    \n    protected $fillable = [\n        'number',\n        'amount',\n        'description',\n        // ... other fields\n    ];\n}\n```\n\n### Direct Operation Permission\n\nFor some users to perform direct operations bypassing the approval process:\n\n```php\n// Grant general direct approval permission (configured in config file)\n$user-\u003egivePermissionTo(config('approvals.permission_name', 'approval_direct'));\n\n// Grant direct approval permission for specific model\n$user-\u003egivePermissionTo(config('approvals.permission_name', 'approval_direct') . ':App\\\\Models\\\\Invoice');\n```\n\n### Managing Approval Requests\n\n```php\nuse Aurorawebsoftware\\AApproval\\Models\\ApprovalRequest;\nuse Aurorawebsoftware\\AApproval\\Models\\ApprovalStep;\n\n// List pending approval requests\n$pendingRequests = ApprovalRequest::where('status', 'pending')-\u003eget();\n\n// Find steps that a specific user can approve\n$user = auth()-\u003euser();\n$approvableSteps = ApprovalStep::where('status', 'pending')\n    -\u003eget()\n    -\u003efilter(function ($step) use ($user) {\n        return $step-\u003ecanUserApprove($user);\n    });\n\n// Approve steps\nforeach ($approvableSteps as $step) {\n    try {\n        $step-\u003eapprove($user);\n        echo \"Step approved: \" . $step-\u003ename;\n    } catch (\\Exception $e) {\n        echo \"Approval error: \" . $e-\u003egetMessage();\n    }\n}\n```\n## 🎯 Example Scenario\n\n```php\n// 1. Define approval flow for Invoice model (in config/approvals.php)\n'App\\\\Models\\\\Invoice' =\u003e [\n    ['name' =\u003e 'Manager Approval', 'type' =\u003e 'role', 'identifier' =\u003e ['manager']],\n    ['name' =\u003e 'Finance Approval', 'type' =\u003e 'role', 'identifier' =\u003e ['finance']],\n]\n\n// 2. Try to create new invoice\n$invoice = new Invoice();\n$invoice-\u003enumber = 'INV-001';\n$invoice-\u003eamount = 5000;\n$invoice-\u003esave(); // This enters approval process, invoice is not created yet\n\n// 3. Manager role user approves\n$managerStep = ApprovalStep::where('status', 'pending')\n    -\u003ewhereHas('approvalRequest', function($q) {\n        $q-\u003ewhere('model_type', 'App\\\\Models\\\\Invoice');\n    })\n    -\u003efirst();\n\n$managerUser = User::role('manager')-\u003efirst();\n$managerStep-\u003eapprove($managerUser);\n\n// 4. Finance role user approves\n$financeStep = ApprovalStep::where('status', 'pending')\n    -\u003ewhere('approval_request_id', $managerStep-\u003eapproval_request_id)\n    -\u003efirst();\n\n$financeUser = User::role('finance')-\u003efirst();\n$financeStep-\u003eapprove($financeUser);\n\n// 5. After all steps are approved, invoice is automatically created\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE.md) file for details.\n\n⭐ Don't forget to star the project if you like it!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faurorawebsoftware%2Faapproval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faurorawebsoftware%2Faapproval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faurorawebsoftware%2Faapproval/lists"}