Laravel Model Cleanup Laravel Package

Technical Evaluation

Architecture Fit

• Pros:
  • Aligns with Laravel’s Eloquent ORM, leveraging existing model structures without invasive changes.
  • Follows a declarative pattern (cleanUp() method) for defining cleanup rules, which is intuitive for developers.
  • Supports batch processing (via clean:models Artisan command), reducing database load during execution.
• Cons:
  • Deprecated: Laravel’s built-in prunable trait (introduced in Laravel 9+) renders this package redundant for most use cases.
  • Architectural Debt: Integrating this package would introduce legacy logic that conflicts with modern Laravel practices (e.g., SoftDeletes + prunable).
  • Limited Flexibility: No support for conditional cleanup (e.g., based on model state, related records, or custom business logic).

Integration Feasibility

• Low Risk for Greenfield Projects: Trivial to implement if cleanup logic is simple (e.g., "delete records older than X days").
• High Risk for Mature Codebases:
  • Conflict with prunable: Laravel’s native solution is more feature-rich (supports dry-run, logging, and scheduled tasks via schedule:run).
  • Database Locking: Bulk deletes may cause contention in high-traffic systems without proper indexing or batching.
  • Testing Overhead: Requires mocking the cleanUp() method and Artisan commands in tests.

Technical Risk

• Maintenance Burden:
  • Security: Unmaintained package may introduce vulnerabilities (e.g., SQL injection if not properly sanitized).
  • Compatibility: Last release in 2020; may break with newer Laravel versions (e.g., Eloquent query builder changes).
• Functional Gaps:
  • No support for:
    • Soft deletes (native Laravel SoftDeletes + prunable handles this).
    • Event hooks (e.g., triggering cleanup on model events).
    • Multi-tenancy (no tenant-aware cleanup logic).
  • Performance: No built-in query optimization (e.g., whereNotIn for related records).

Key Questions

1. Why not use Laravel’s prunable?
   • Does the team require pre-Laravel 9 compatibility?
   • Are there unsupported features (e.g., custom cleanup logic) not covered by prunable?
2. Database Impact:
   • What is the expected volume of records to clean? (Risk of long-running transactions.)
   • Are there foreign key constraints that could block deletes?
3. Operational Workflow:
   • How will cleanup be scheduled? (Cron vs. Laravel’s task scheduler.)
   • Are there audit requirements for deleted records?
4. Migration Path:
   • Can existing cleanup logic be refactored to use prunable incrementally?
   • Are there custom cleanup rules that cannot be expressed with prunable?

Integration Approach

Stack Fit

• Laravel 8 or Below: Ideal for projects unable to upgrade to Laravel 9+ (due to prunable dependency).
• PHP 7.4+: Compatible with Laravel’s supported PHP versions.
• Database Agnostic: Works with MySQL, PostgreSQL, SQLite, etc., but performance may vary.
• Queue Integration: Can be extended to run cleanup jobs asynchronously (though not built-in).

Migration Path

1. Assessment Phase:
   • Audit existing cleanup logic to identify gaps vs. prunable capabilities.
   • Document all cleanUp() methods and their rules.
2. Hybrid Approach (Recommended):
   • Short-Term: Use spatie/laravel-model-cleanup for legacy systems with minimal changes.
   • Long-Term: Migrate to prunable by:
     • Replacing cleanUp() methods with prunable traits.
     • Using Laravel’s scheduler (App\Console\Kernel.php) for periodic cleanup.
     • Leveraging prunable's dry-run and logging features.
3. Refactoring Steps:
   • Step 1: Add prunable trait to models and replicate cleanup rules.
   • Step 2: Replace clean:models Artisan command with schedule:run in a cron job.
   • Step 3: Deprecate the package and remove it in a future release.

Compatibility

• Laravel Versions:
  • Officially supports Laravel 5.8–8.x. Test thoroughly for edge cases in newer versions.
• Eloquent Features:
  • Works with SoftDeletes, but cleanup targets all records (not just soft-deleted ones).
  • No native support for Scopes or Global Scopes in cleanup queries.
• Third-Party Dependencies:
  • None; pure Laravel/Eloquent integration.

Sequencing

1. Pre-Integration:
   • Back up databases and test cleanup in a staging environment.
   • Verify foreign key constraints won’t block deletes.
2. Implementation:
   • Register models in config/model-cleanup.php.
   • Implement cleanUp() methods for each model.
   • Schedule clean:models via cron (e.g., * * * * * php artisan clean:models).
3. Post-Integration:
   • Monitor database performance and cleanup logs.
   • Plan migration to prunable within 6–12 months.

Operational Impact

Maintenance

• Proactive:
  • Deprecation Risk: Requires active monitoring for Laravel version compatibility.
  • Custom Logic: Any extensions (e.g., conditional cleanup) must be maintained manually.
• Reactive:
  • Bug Fixes: No official support; issues must be resolved via community or forks.
  • Security Patches: Vulnerabilities will not be addressed post-2020.

Support

• Documentation:
  • README and changelog are clear but outdated (no mention of prunable).
  • No official support channels (GitHub issues may be ignored).
• Troubleshooting:
  • Common issues:
    • "Command not found" (ensure package is registered in config/app.php).
    • "SQLSTATE[23000]" (foreign key violations; requires manual constraint handling).
    • Performance bottlenecks (no built-in batching for large datasets).
• Community:
  • Limited activity; rely on Laravel’s broader ecosystem for alternatives.

Scaling

• Performance:
  • Bulk Deletes: Risk of long-running transactions if not batched.
    • Mitigation: Use Laravel’s chunk() method in custom cleanup logic.
  • Database Load: High-frequency cleanup may impact read operations.
    • Mitigation: Schedule during off-peak hours or use queue workers.
• Horizontal Scaling:
  • Stateless package; no impact on scaling Laravel horizontally.
• Data Volume:
  • Limitations: No built-in pagination or cursor-based cleanup for large tables.
    • Workaround: Implement custom chunking in cleanUp() method.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • Time to Proficiency: 1–2 hours for basic setup; longer for custom logic.
  • Key Concepts:
    • cleanUp() method signature and CleanupConfig options.
    • Artisan command usage and scheduling.
• Operational Training:
  • Monitoring: Log cleanup events (e.g., Log::info("Cleaned up X records")).
  • Alerting: Set up alerts for failed cleanup jobs.
• Knowledge Transfer:
  • Document all cleanUp() rules and their business justification.
  • Train teams on the migration path to prunable.