Filament Withdrawals Laravel Package

Technical Evaluation

Architecture Fit

• Filament Integration: The package is a Filament plugin, extending Laravel's Filament admin panel. Natural fit for projects already on Filament; no parallel UI stack required.
• Domain-Specific: Targets withdrawal management (methods, requests, approvals), aligning with fintech, SaaS, or e-commerce payout workflows.
• Modular Design: Supports custom form fields and form builders for unique withdrawal logic (KYC gates, fee structures, approval chains).
• Configuration-Driven Security Boundary (new in v5.0.1): Relation fields are now governed by a relations allowlist in config/filament-withdrawals.php. This converts a previously dynamic, editor-controlled query surface into an explicit, operator-owned policy. Architecturally sound, but it introduces a new required configuration artifact that must be owned and maintained.
• Database Agnostic: Publishable Laravel migrations remain compatible with MySQL, PostgreSQL, and SQLite.

Integration Feasibility

• Low Coupling: Minimal core changes — Composer dependency, filament-withdrawals:install, plugin registration in AdminPanelProvider, plus (new) config publishing if relation fields are used.
• Filament Dependency: Hard requirement on Filament. Non-Filament projects face a UI adoption cost.
• Laravel/PHP Version: Confirm constraints in composer.json; the v5 line implies a recent Filament major. Verify before committing.
• New Upgrade Friction (v5.0.1): The allowlist ships empty. Any existing withdrawal method using relation fields will render with no options until the config is published and populated. This is a behavioral regression by design, not a schema break — but it will visibly break configured forms if the upgrade is applied without the config step.
• Third-Party Risks: Filament ecosystem dependencies (e.g. media library for uploads) remain a version-conflict surface.

Technical Risk

Key Questions

1. Exposure Assessment: Was any version prior to v5.0.1 deployed to staging or production? Were relation fields configured, and with which model/column pairs? Were password hashes or other hidden attributes ever rendered in a form? This determines whether an incident review is required.
2. Relation Field Usage: Do any current or planned withdrawal methods depend on relation fields? If yes, the allowlist is a hard prerequisite, not an optional hardening step.
3. Allowlist Ownership: Who approves additions to config/filament-withdrawals.php? Is it code-reviewed like a schema or permission change?
4. Editor Authorization: Which roles can access the withdrawal form/field editor today? Should that be narrowed?
5. Filament/Laravel Versions: What is in use or planned, and does it satisfy the v5 line's constraints?
6. Customization Needs: Non-standard workflows (multi-step approvals, dynamic fees) requiring custom fields or builders?
7. Scalability: Expected concurrent withdrawal volume and peak approval throughput?
8. Support & Maintenance: Release cadence and open-issue posture. Note that a security release of this severity is a positive maintenance signal, but the package remains low-adoption — plan for self-support.

Integration Approach

Stack Fit

• Primary Stack: Laravel + Filament. Native integration, shared auth, UI consistency; tight coupling to Filament is the trade-off.
• Secondary Stack: PHP 8.1+, MySQL/PostgreSQL via Laravel.
• Configuration Surface (expanded): config/filament-withdrawals.php is now a first-class integration artifact alongside migrations and language files. Treat it as deployable configuration under version control.
• Extensions: Custom form fields via service providers; validation via Laravel form requests; publishable language files.

Migration Path

1. Prerequisites:
   • Confirm Laravel/Filament compatibility with the v5 line.
   • Validate database support for the package schema (e.g. decimal for balances).
2. Installation:

   composer require tomatophp/filament-withdrawals
   php artisan filament-withdrawals:install
   

3. Configuration:
   • Register the plugin in AdminPanelProvider.php.
   • Publish config, migrations, and language files as needed:

     php artisan vendor:publish --tag="filament-withdrawals-config"
     php artisan vendor:publish --tag="filament-withdrawals-migrations"
     php artisan vendor:publish --tag="filament-withdrawals-lang"
     

   • Populate the relations allowlist (required if relation fields are used):

     'relations' => [
         \App\Models\Bank::class => ['name'],
     ],
     

4. Remediation of Pre-Existing Installations:
   • Upgrade to v5.0.1 before any further feature work.
   • Inventory existing withdrawal form definitions and enumerate referenced model/column pairs.
   • Map each to a minimal allowlist entry; drop anything unnecessary.
   • Re-save forms through the field editor so values pass the new server-side validation.
5. Testing:
   • Verify withdrawal methods, requests, and approval flows.
   • Explicitly test relation-field rendering with both allowlisted and non-allowlisted values (non-allowlisted must render empty and must not query).
   • Test edge cases: insufficient funds, duplicate requests, retries.

Compatibility

Sequencing

1. Phase 0: Security Triage (do first)
   • Determine prior exposure; preserve relevant form definitions and access logs before cleanup.
   • Notify security stakeholders; decide on incident process.
2. Phase 1: Upgrade + Config
   • Upgrade to v5.0.1.
   • Publish config, populate the allowlist, and re-validate forms — deployed atomically with the upgrade.
3. Phase 2: Core Integration
   • Register plugin, publish migrations, migrate existing withdrawal data if applicable.
   • Narrow field-editor permissions.
4. Phase 3: Customization
   • Extend form fields/builders; add validation via form requests.
5. Phase 4: Testing & Optimization
   • Load test approval flows; index withdrawal_requests.
   • Negative-test the allowlist (non-allowlisted model/column yields no options, no query).
6. Phase 5: Deployment
   • Roll out to staging, then production, with monitoring for failed transactions and empty relation fields.

Operational Impact

Maintenance

• Security Patching Cadence: This release sets an expectation that security fixes arrive as patch versions requiring operator action. Subscribe to releases and define an SLA for applying security patches to payout-adjacent code.
• Allowlist as Standing Config: Every new relation field now requires a reviewed config change and redeploy. Budget for this in feature delivery; it is a small but permanent tax.
• Vendor Updates: Monitor the package for breaking changes (MIT license permits forks). Update Filament/Laravel in lockstep.
• Custom Code: Extensions depend on the package's field/form APIs, which may shift between majors.
• Backup Strategy: Back up withdrawal_requests and withdrawal_methods before upgrades; config lives in version control.

Support

• Troubleshooting: Debugging spans Filament internals (resources, policies) and the new allowlist layer. "Empty relation dropdown" is now a top-tier support symptom with a known cause.
• Documentation: The upgrade note is clear but terse; internal runbooks should document the allowlist workflow end to end, including how to add a model/column safely.
• Community Support: Low adoption (small star/dependent count) — expect self-support via GitHub issues and Filament forums.
• Error Handling: Failed withdrawals still require custom logging (report(), Sentry); add alerting for relation fields rendering empty in production.

Scaling

• Performance Bottlenecks: Filament tables slow beyond ~10K records — index status/created_at, paginate, lazy load. High volume requires queue-based processing and read replicas for reporting.
• Horizontal Scaling: Stateless Filament UI; scale Laravel workers/queues. Sharding beyond ~1M requests.
• Allowlist at Scale: A permissive allowlist can reintroduce expensive ::all()-style queries on large tables. Scope columns tightly and monitor query time on relation-backed fields.

Failure Modes

Ramp-Up

• Developer Onboarding: 2–4 hours for basic setup; 1–2 days for full customization. Add ~2–4 hours for security-context onboarding (allowlist model, editor permissions, exposure history).
• Key Learning Curves: Filament resource/controller structure; the package's form builder and field classes; the allowlist resolution path and its validation rules.
• Training Needs: Document the allowlist workflow, the approval path for config changes, and the incident playbook for a suspected data exposure. Ensure support staff can distinguish "empty relation field = misconfigured allowlist" from a functional bug before escalating.
• Security Culture: Brief the team that this class of defect came from trusting editor-supplied input as a query specification — a pattern to look for in other admin-configurable features.