- How do I implement approval workflows for Eloquent models in Laravel using this package?
- Add the `MustBeApproved` trait to your model and publish the migrations/config. The package automatically stages new records in a pending state, requiring explicit approval via `approve()` or rejection via `reject()`. Custom workflows can be extended using the `ApprovalStatus` enum or config.
- What Laravel and PHP versions does this package support?
- The package requires **PHP 8.3+** and **Laravel 12.4+ or 13.x**. Laravel 11 support was dropped in v2.1, so upgrade or pin to `^2.0` if still using EOL versions. Check the [upgrade guide](https://github.com/cjmellor/approval/blob/main/UPGRADE.md) for migration steps.
- Can I customize approval states beyond 'pending', 'approved', and 'rejected'?
- Yes. The package uses an `ApprovalStatus` enum, which can be extended via the `config/approval.php` file. Add custom states (e.g., 'under_review') and update your logic to handle them, but avoid excessive states to prevent UI/complexity bloat.
- How does this package handle large JSON payloads for model data?
- The package stores `new_data` and `original_data` as JSON in the `approvals` table. While flexible, this can bloat storage and slow queries. For high-write workloads, test performance with production-like data volumes and consider partial indexes on `approvalable_type` or `id` to optimize queries.
- Does this package support hierarchical or multi-level approvals (e.g., team leads + managers)?
- No, the package doesn’t natively support hierarchical approvals. Each model requires a single approval action. For multi-level workflows, extend the `ApprovalStatus` enum or implement custom logic (e.g., trigger a new approval when a team lead approves).
- How do I handle concurrent edits to a model during the approval process?
- The package doesn’t lock models during approval, so race conditions can occur if multiple users edit the same staged record. Mitigate this by implementing optimistic locking (e.g., `version` column) or application-level locks in your UI/API.
- Can I use this package with Laravel Nova/Panel for admin approval dashboards?
- Yes. The package integrates seamlessly with Nova/Panel. Use the `MustBeApproved` trait on your models, then build custom Nova tools or Panel actions to approve/reject records. The `Approval` model provides all necessary data (e.g., `new_data`, `actioned_at`).
- How do I test approval workflows, including rollbacks and expirations?
- The package includes unit tests, but you should automate end-to-end testing for critical workflows (e.g., approval → rejection → rollback). Use Laravel’s testing tools to mock events like `ModelApproved` or `ApprovalExpired`, and verify database state changes.
- What are the performance implications of using JSON columns for storing model data?
- JSON columns add CPU/memory overhead during serialization/deserialization, especially for nested models. Benchmark with high-write workloads. For large payloads, consider denormalizing critical fields into separate columns or using a dedicated queue to process approvals asynchronously.
- Are there alternatives to this package for Laravel model approvals?
- Alternatives include **Spatie’s Laravel Activitylog** (for auditing) + custom logic, **Laravel Policy** (for authorization), or **Filament’s Approval system** (if using Filament). This package stands out for its **polymorphic support**, **event-driven design**, and **built-in rollback** features, but choose based on your need for simplicity vs. flexibility.