Cleaner Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The package targets data cleanup/archival (e.g., logs, cache, temporary files, database records) via configurable retention policies. This aligns with:
  • Event-driven systems (e.g., post-processing cleanup after job completion).
  • Cost optimization (e.g., S3, database bloat, or cache eviction).
  • Compliance-driven retention (e.g., GDPR, CCPA).
• Laravel Ecosystem Fit: Leverages Laravel’s service providers, scheduler, and queue workers, making it pluggable into existing workflows (e.g., Artisan commands, cron jobs, or event listeners).
• Storage Agnosticism: Supports filesystems (local/S3), databases (MySQL/Postgres), and caches (Redis), but lacks native support for NoSQL (e.g., MongoDB) or message queues (e.g., RabbitMQ). May require custom adapters.

Integration Feasibility

• Low-Coupling Design: Uses strategy pattern (via Cleaner facade) to define rules per storage type. Easy to extend for custom storages.
• Dependency Risks:
  • Laravel Version Lock: Last release in 2021 targets Laravel 8.x. Integration with Laravel 10/11 may require:
    • Compatibility fixes (e.g., Illuminate\Support\Facades\Storage changes).
    • Dependency conflicts (e.g., spatie/laravel-activitylog if using similar patterns).
  • PHP 8.x Support: Unclear if the package handles named arguments or attributes (e.g., #[\Override]). Test with PHP 8.1+.
• Configuration Overhead:
  • Requires YAML/JSON rule definitions for each storage (e.g., cleaner.php). May need validation for complex retention logic.
  • No built-in dry-run mode or audit logging (critical for production).

Technical Risk

Key Questions

1. Storage Support Gaps:
   • Does the target system use unsupported storages (e.g., Elasticsearch, MongoDB)?
   • Are there custom storage adapters already in use that could conflict?
2. Retention Logic Complexity:
   • Are cleanup rules static (e.g., "delete logs >30 days") or dynamic (e.g., user-specific policies)?
   • Is there a need for conditional cleanup (e.g., only delete inactive users)?
3. Observability:
   • How will cleanup operations be monitored (e.g., logs, metrics, alerts)?
   • Are there SLA requirements for cleanup job completion?
4. Rollback Strategy:
   • How will accidental deletions be recovered (e.g., backups, event sourcing)?
5. Alternatives Assessment:
   • Compare with native Laravel solutions (e.g., Model::where()->delete() + scheduled tasks) or dedicated tools (e.g., AWS S3 Lifecycle Policies).

Integration Approach

Stack Fit

• Laravel-Centric: Ideal for monolithic Laravel apps with:
  • Artisan commands for manual triggers.
  • Task Scheduling (app/Console/Kernel.php) for automated runs.
  • Queue Workers (if extending for async cleanup).
• Non-Laravel Systems:
  • Symfony/PHP CLI: Possible but requires rewriting service provider bindings.
  • Microservices: Poor fit due to Laravel dependencies (e.g., Illuminate/Contracts).

Migration Path

1. Assessment Phase:
   • Audit existing cleanup logic (e.g., cron jobs, manual scripts).
   • Map storage types to lamoda/cleaner adapters (or identify gaps).
2. Pilot Integration:
   • Start with low-risk storages (e.g., logs, cache).
   • Use feature flags to toggle cleanup between old/new systems.
3. Full Rollout:
   • Replace legacy cleanup jobs with Cleaner facade calls.
   • Migrate to Laravel Scheduler for orchestration.
4. Deprecation:
   • Phase out old scripts post-validation.

Compatibility

Sequencing

1. Pre-requisites:
   • Ensure Laravel scheduler is configured (schedule:run in cron).
   • Set up queue workers if using async cleanup.
2. Configuration:
   • Define cleanup rules in config/cleaner.php (e.g., logs: { "retention": "30 days" }).
   • Extend StorageAdapter for custom storages.
3. Testing:
   • Unit Tests: Mock adapters to test rule evaluation.
   • Integration Tests: Verify cleanup in staging (e.g., delete test logs).
   • Load Tests: Simulate large datasets (e.g., 100K records).
4. Deployment:
   • Roll out to non-production first.
   • Monitor error logs and job execution time.

Operational Impact

Maintenance

• Pros:
  • Centralized Rules: All cleanup logic in config/cleaner.php (easy to update).
  • Extensible: Add new storages without core changes.
• Cons:
  • Archived Package: No updates since 2021 → forking required for fixes.
  • Documentation Gaps: Lack of usage examples or troubleshooting guides.
• Ongoing Tasks:
  • Rule Updates: Adjust retention policies as compliance requirements evolve.
  • Adapter Maintenance: Patch custom adapters for storage API changes.

Support

• Debugging Challenges:
  • Lack of Observability: No built-in logging for cleanup operations.
  • Error Handling: Generic exceptions may obscure root causes (e.g., failed DB queries).
• Recommended Add-ons:
  • Integrate Laravel Horizon for queue monitoring.
  • Add custom logging (e.g., Cleaner::clean([...])->log()).
  • Use Sentry for error tracking.
• Support Matrix:

  Issue Type	Resolution Path
  Laravel Version	Fork/rebase or use compatibility layer.
  Storage Adapter	Extend StorageAdapter interface.
  Rule Logic Errors	Add validation in CleanerServiceProvider.
  Performance Issues	Optimize batch size or use queues.

Scaling

• Horizontal Scaling:
  • Queue-Based: Offload cleanup to workers (e.g., Cleaner::clean()->onQueue('cleanup')).
  • Batch Processing: Use chunk() for database cleanup to avoid locks.
• Vertical Scaling:
  • Memory Limits: Large cleanup jobs may hit PHP memory limits (adjust memory_limit).
  • Database Load: Test with DB::transaction() to avoid long-running transactions.
• Scaling Bottlenecks:
  • Single-Threaded: No native parallelism (mitigate with queues).
  • Storage API Limits: Some adapters (e.g., S3) may hit rate limits (implement retries).

Failure Modes