Livewire Tmp Cleanup Laravel Package

Technical Evaluation

Architecture Fit

• Problem Alignment: Directly addresses a critical gap in Laravel/Livewire deployments where temporary uploads (e.g., file uploads via livewire:model) persist indefinitely on S3-compatible storage due to lack of native lifecycle management. Ideal for serverless/cloud environments (e.g., Laravel Cloud, Forge) where S3 lifecycle rules are unavailable.
• Non-Invasive: Operates as a standalone Artisan command with zero Livewire core modifications, adhering to Laravel’s modular design. Leverages existing Laravel scheduler (schedule:run) for execution.
• Extensibility: Configurable disk/directory paths and age thresholds (hours) allow customization for multi-disk setups or compliance requirements (e.g., GDPR retention policies).
• Event-Driven Potential: Could be extended to emit events (e.g., TmpCleanupExecuted) for audit logging or triggering downstream actions (e.g., analytics).

Integration Feasibility

• Low Coupling: Only requires:
  • Laravel 8+ (Livewire 2+ compatibility implied).
  • Flysystem S3 disk configuration (already standard in Laravel).
  • Scheduler enabled (APP_SCHEDULER_ENABLED=true).
• Dependency Risk: Minimal—only relies on Laravel’s core scheduler and Flysystem. No external APIs or heavy libraries.
• Testing: Unit-testable via Artisan command testing (e.g., Artisan::call()) and mock S3 disks (e.g., MockFlysystemAdapter).

Technical Risk

• S3 Provider Quirks: Potential edge cases with:
  • Cloudflare R2: May require custom metadata handling (R2 lacks S3’s LastModified precision).
  • MinIO: Object locking or versioning could interfere with deletion logic.
  • Rate Limits: High-volume cleanup might trigger S3 API throttling (mitigate with withoutOverlapping()).
• Livewire Version Drift: Risk if Livewire changes its temporary_file_upload disk/directory structure (monitor Livewire releases).
• Dry-Run Validation: Current dry-run mode is manual; could benefit from automated pre-deployment validation (e.g., CI check).
• Concurrency: onOneServer() ensures single-server execution, but no distributed lock mechanism for multi-server setups (e.g., Laravel Horizon).

Key Questions

1. Storage Provider Compatibility:
   • Are there known issues with [specific S3 provider X] (e.g., Backblaze B2, DigitalOcean Spaces)?
   • How does the package handle non-standard S3 metadata (e.g., custom x-amz-* headers)?
2. Performance:
   • What’s the expected runtime for 100K+ temporary files? Can it be parallelized?
   • How are large directories (e.g., 1M+ files) handled? (Risk of timeout or memory issues.)
3. Safety:
   • Is there a way to whitelist files (e.g., exclude files with is_processed=true metadata)?
   • How are partial uploads (e.g., interrupted transfers) handled?
4. Observability:
   • Are cleanup logs (deleted files, errors) structured for monitoring (e.g., Laravel Horizon, Sentry)?
   • Can it emit metrics (e.g., Prometheus) for deleted files/bytes?
5. Future-Proofing:
   • Will it support Livewire’s upcoming features (e.g., tmp_upload disk changes)?
   • Any plans for async cleanup (e.g., queues) to avoid blocking scheduler?

Integration Approach

Stack Fit

• Laravel Ecosystem: Native fit for Laravel apps using Livewire + S3/Flysystem. No framework changes required.
• Cloud Providers:
  • Laravel Cloud/Forge: Ideal for serverless deployments where S3 lifecycle rules are unavailable.
  • AWS/GCP: Works alongside existing S3 lifecycle policies (can act as a fallback).
  • Edge Cases: May need adjustments for non-S3 storage (e.g., local disks, SFTP).
• Alternatives Considered:
  • S3 Lifecycle Rules: Preferable but not always available (e.g., R2, shared accounts).
  • Custom Cron Job: More maintenance than this package’s auto-scheduling.
  • Livewire Events: No built-in cleanup hooks; this fills the gap.

Migration Path

1. Pre-Integration:
   • Audit existing temporary uploads: php artisan storage:link + S3 disk config.
   • Verify Livewire’s temporary_file_upload disk/directory in config/filesystems.php.
2. Installation:

   composer require bnzo/livewire-tmp-cleanup
   php artisan vendor:publish --provider="Bnzo\LivewireTmpCleanup\LivewireTmpCleanupServiceProvider"
   

   • Publish config to adjust cleanup_age (default: 24 hours) and disk/directory.
3. Testing:
   • Run dry-run manually: php artisan livewire-tmp:clean --dry-run.
   • Validate against a test S3 bucket with known old files.
4. Deployment:
   • Enable scheduler in .env: APP_SCHEDULER_ENABLED=true.
   • Add to app/Console/Kernel.php (already auto-registered):

     $schedule->command('livewire-tmp:clean')->daily()->onOneServer()->withoutOverlapping();
     

   • Run php artisan schedule:run manually for initial cleanup.

Compatibility

• Laravel Versions: Tested on Laravel 8+ (assume Livewire 2+ compatibility).
• PHP Versions: Requires PHP 8.0+ (aligns with Laravel 8+).
• S3 Providers: Officially supports AWS S3, Cloudflare R2, MinIO. Unofficial support for others depends on Flysystem adapter compliance.
• Livewire: Assumes standard temporary_file_upload disk. Custom Livewire setups may need config overrides.

Sequencing

1. Phase 1: Install and configure for a non-production environment.
2. Phase 2: Run dry-run and validate against a subset of old files.
3. Phase 3: Monitor logs for errors (e.g., permission issues, missing files).
4. Phase 4: Gradually increase cleanup_age in production (e.g., start with 48 hours).
5. Phase 5: (Optional) Extend for multi-disk support or custom metadata filtering.

Operational Impact

Maintenance

• Low Overhead:
  • Single Artisan command with zero runtime dependencies.
  • Configurable via .env or published config (no code changes).
• Updates:
  • Minor updates likely for bug fixes (e.g., S3 provider quirks).
  • Major updates may require testing if Livewire’s disk structure changes.
• Deprecation Risk: Minimal; MIT license ensures long-term viability.

Support

• Troubleshooting:
  • Logs cleanup actions to Laravel’s default log (storage/logs/laravel.log).
  • Dry-run mode aids debugging without data loss.
• Common Issues:
  • Permissions: Ensure S3 IAM roles have s3:DeleteObject permissions.
  • Disk Mismatch: Verify temporary_file_upload disk matches Livewire’s config.
  • Timezone: Cleanup uses server timezone; adjust cleanup_age if needed.
• Documentation: README is sufficient for basic setup; may need internal runbooks for edge cases.

Scaling

• Horizontal Scaling:
  • onOneServer() prevents duplicate runs in multi-server setups.
  • For large-scale cleanup, consider:
    • Chunking: Process files in batches (e.g., 1000 at a time) to avoid timeouts.
    • Queues: Offload to Laravel queues for async processing (requires custom implementation).
• Performance Bottlenecks:
  • S3 API calls are the primary constraint. Mitigate with:
    • Caching: Cache disk listings if frequent runs are needed.
    • Provider-Specific Optimizations: Use S3’s ListObjectsV2 with MaxKeys for pagination.
• Cost Impact: Minimal; cleanup reduces storage costs by removing stale files.

Failure Modes

Ramp-Up

• Onboarding Time: <1