shahajahan/approval-flow

A dynamic, framework-agnostic approval access control system for any PHP framework (Laravel, CodeIgniter, CakePHP, Symfony, or plain PHP). Define and manage multi-level approval roles, with forward/backward flow and permission checks.

1.0.0 2025-10-13 08:15 UTC

Requires

• php: >=5.6

Requires (Dev)

• phpunit/phpunit: ^9.6

MIT

• Md Shahajahan Ali

README

A dynamic approval access control system for any PHP framework (Laravel, CodeIgniter, CakePHP, Symfony, or plain PHP). Define and manage multi-level approval roles, with forward/backward flow and permission checks — all framework-agnostic.

🚀 Features

✅ Framework-agnostic core ✅ Works with Laravel, CodeIgniter, Symfony, CakePHP, or raw PHP ✅ Dynamic approval hierarchy (forward/backward flow) ✅ Dynamic approval (forward/backward flow) with multiple approval flow on same project ✅ Simple adapter pattern for DB access (PDO, Query Builder, or ORM) ✅ PSR-4 and PSR-12 compliant ✅ Extensible and testable

🧩 Installation

Via Composer

composer require shahajahan/approval-flow

If you’re developing locally, clone the repo and link:

git clone https://github.com/shahajahancse/approval-flow.git
cd approval-flow
composer install

🗃️ Database Schema

The recommended database schema is defined in database/schema.sql. You can use this file to set up your tables. A migration file for Laravel is also available at database/migrations/2025_10_13_000000_create_approval_tables.php.

⚙️ Usage Examples

🔹 Laravel

use ApprovalFlow\Services\ApprovalFlow;
use ApprovalFlow\Adapters\LaravelAdapter;

$flow = new ApprovalFlow(new LaravelAdapter());

$nextRole = $flow->nextRole(2);
$prevRole = $flow->previousRole(2);
$canApprove = $flow->canApprove(auth()->id(), $documentId);

🔹 CodeIgniter (v3 or v4)

$flow = new \ApprovalFlow\Services\ApprovalFlow(
    new \ApprovalFlow\Adapters\CodeIgniterAdapter($this)
);

$next = $flow->nextRole($currentRoleId);
$canApprove = $flow->canApprove($user_id, $doc_id);

🔹 Symfony

use ApprovalFlow\Services\ApprovalFlow;
use ApprovalFlow\Adapters\SymfonyAdapter;
use Doctrine\ORM\EntityManagerInterface;

// Assuming you have injected the EntityManager
$adapter = new SymfonyAdapter($entityManager);
$flow = new ApprovalFlow($adapter);

$nextRole = $flow->nextRole(1);

🔹 CakePHP

use ApprovalFlow\Services\ApprovalFlow;
use ApprovalFlow\Adapters\CakePHPAdapter;
use Cake\ORM\TableRegistry;

// Get the default ORM table
$usersTable = TableRegistry::getTableLocator()->get('Users');
$adapter = new CakePHPAdapter($usersTable);
$flow = new ApprovalFlow($adapter);

$nextRole = $flow->nextRole(1);

🔹 Plain PHP (PDO)

use ApprovalFlow\Services\ApprovalFlow;
use ApprovalFlow\Adapters\PdoAdapter;

$pdo = new PDO("mysql:host=localhost;dbname=test", "root", "");
$adapter = new PdoAdapter($pdo);
$flow = new ApprovalFlow($adapter);

if ($flow->canApprove(1, 100)) {
    echo "User can approve document!";
}

🧠 Architecture

• Core Logic: ApprovalFlow (framework-independent)
• Adapters:
  • LaravelAdapter — Uses Laravel’s Query Builder (DB Facade)
  • CodeIgniterAdapter — Uses CI’s $this->db query builder
  • PdoAdapter — Uses native PDO
• Contract: ApproverInterface ensures consistency across adapters

🧰 Helper Functions

approval_log("Approval started...");
// Output: [ApprovalFlow] 2025-10-13 11:00:00 - Approval started...

🧪 Running Tests

./vendor/bin/phpunit --bootstrap vendor/autoload.php tests

Sample test (tests/ApprovalFlowTest.php) is already included.

🧱 Folder Structure

approval-flow/
│
├── src/
│   ├── Contracts/ApproverInterface.php
│   ├── Services/ApprovalFlow.php
│   ├── Adapters/
│   │   ├── LaravelAdapter.php
│   │   ├── CodeIgniterAdapter.php
│   │   └── PdoAdapter.php
│   └── Helpers/helper.php
│
├── tests/
│   └── ApprovalFlowTest.php
└── composer.json

🪪 License

This package is open-sourced software licensed under the MIT license.

👨‍💻 Author

Md Shahajahan Ali 📧 [e-mail] 🌐 GitHub: @shahajahan

🌟 Contributing

Pull requests are welcome! To contribute:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/your-feature)
3. Commit changes and push
4. Submit a Pull Request 🎯

💡 Future Enhancements

• Approval workflow templates (Leave, Expense, Purchase)
• Event hooks (onApprove, onReject)
• JSON-based flow configuration
• Role-based escalation and notifications