Laravel File Management Laravel Package

Getting Started

This package provides a robust file management system for Laravel applications, handling core CRUD operations with trash functionality. To begin, install via Composer:

composer require vendor/package-name

Publish the configuration and migrations (if applicable) to customize behavior:

php artisan vendor:publish --provider="Vendor\PackageName\PackageServiceProvider"
php artisan migrate

First Use Case: Upload a file and handle its lifecycle:

use Vendor\PackageName\Facades\FileManager;

// Upload a file
$file = FileManager::upload($request->file('file'), 'storage/path');

// Trash the file (soft delete)
$file->trash();

// Restore from trash
$file->restore();

// Permanently delete
$file->delete();

// Update metadata (e.g., custom attributes)
$file->update(['custom_field' => 'value']);

Key classes to explore:

• FileManager facade (main entry point)
• File model (represents managed files)
• Trash helper (for soft-deleted files)

Implementation Patterns

Core Workflows

1. File Upload & Storage Use FileManager::upload() with a Uploadable interface-compliant file (Laravel UploadedFile or custom). Specify a destination path (relative to storage/app by default). Example:

   $file = FileManager::upload($request->file('document'), 'contracts/{year}');
   

2. Lifecycle Management Leverage soft-deletes for compliance/retention:

   // Bulk trash files by directory
   FileManager::trashDirectory('contracts/2023');
   
   // Restore all trashed files
   FileManager::restoreTrashed();
   

3. Metadata & Extensions Attach custom attributes to files via update():

   $file->update([
       'client_id' => $client->id,
       'expiry_date' => now()->addYear(),
   ]);
   

Integration Tips

• Events: Bind to file.uploaded, file.trashed, etc., in EventServiceProvider:

  protected $listen = [
      'Vendor\PackageName\Events\FileUploaded' => [
          'App\Listeners\LogUpload',
      ],
  ];
  

• Validation: Use FileManager::rules() for form validation:

  $request->validate([
      'file' => ['required', FileManager::rules()->maxSize(10 * 1024)->allowedTypes(['pdf'])]
  ]);
  

• API Responses: Serialize files with FileResource:

  return new FileResource($file);
  

Gotchas and Tips

Pitfalls

1. Trash Retention By default, trashed files are not purged automatically. Schedule a cleanup job:

   // config/package.php
   'trash_retention_days' => 30, // Default: 30 days
   

   Use FileManager::purgeTrash() to manually delete old files.

2. Path Resolution Paths are resolved relative to storage/app. Avoid hardcoding absolute paths in logic. Use:

   $fullPath = FileManager::getFullPath($file->path);
   

3. Concurrency File operations (e.g., update()) may conflict if multiple requests target the same file. Use optimistic locking:

   $file->update(['views' => $file->views + 1], ['lock_for_update' => true]);
   

Debugging

• Log File Operations: Enable debug mode in config:

  'debug' => env('APP_DEBUG', false),
  

• Check Trash: Inspect trashed files via:

  $trashed = FileManager::trashedFiles()->get();
  

• Disk Issues: Verify the configured disk (config/filesystems) has write permissions.

Extension Points

1. Custom Storage Override the default disk by binding a FileStorage implementation:

   $app->bind('Vendor\PackageName\Contracts\FileStorage', function () {
       return new S3FileStorage();
   });
   

2. File Events Extend core events (e.g., FileUploaded) by publishing event classes:

   php artisan vendor:publish --tag=package-events
   

3. Validation Rules Create custom rules by extending FileValidationRule:

   class CustomRule extends FileValidationRule {
       public function passes($attribute, $value) {
           // Custom logic
       }
   }
   

   Register via config:

   'validation_rules' => [
       'custom_rule' => \App\Rules\CustomRule::class,
   ],