Laravel File Management Image Laravel Package

Getting Started

This package provides a robust file management system for Laravel applications, handling core CRUD operations for file storage with a focus on uploads, trash management, and restoration. To begin:

1. Installation: Require the package via Composer:

   composer require vendor/package-name
   

2. Publish Config: Run the package publisher to configure storage paths, disk settings, and soft-delete behavior:

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

3. Basic Upload: Use the upload facade or service class to handle file uploads:

   use Vendor\PackageName\Facades\FileManager;
   
   $file = FileManager::upload($request->file('document'), 'documents');
   

4. First Use Case: Upload a file and immediately access its metadata:

   $file = FileManager::upload($request->file('image'), 'images');
   $file->path; // Full path to the file
   $file->url;  // Publicly accessible URL
   

Implementation Patterns

Core Workflows

1. File Uploads

   • Use FileManager::upload() with a file and target directory:

     $file = FileManager::upload($request->file('file'), 'uploads');
     

   • Supports custom disk configurations via the disk parameter:

     $file = FileManager::upload($request->file('file'), 'uploads', 's3');
     

2. Trash Management

   • Soft-delete files to the trash:

     FileManager::trash($fileId); // Returns trashed file model
     

   • Restore trashed files:

     FileManager::restore($trashedFileId);
     

   • Permanently delete trashed files:

     FileManager::delete($trashedFileId);
     

3. Bulk Operations

   • Trash multiple files:

     FileManager::trash([$fileId1, $fileId2]);
     

   • Restore all trashed files in a directory:

     FileManager::restoreTrashed('documents');
     

Integration Tips

• Model Observers: Extend the package’s FileObserver to trigger custom logic on file events (e.g., saved, deleted).
• Events: Listen for package events like FileUploaded, FileTrashed, or FileRestored:

  event(new FileUploaded($file));
  

• Middleware: Use the FileManager middleware to validate file uploads before processing:

  Route::middleware('file.manager')->group(function () {
      // Routes requiring file management
  });
  

Gotchas and Tips

Pitfalls

1. Disk Configuration

   • Ensure the disks array in the published config matches your Laravel filesystems.php settings. Mismatches will cause silent failures during uploads.
   • Default disk is public; explicitly specify disk for S3/other drivers:

     FileManager::upload(..., 'uploads', 's3');
     

2. Trash Lifecycle

   • Trashed files are not immediately deleted from disk. Use FileManager::cleanTrash() to purge old trashed files (configured via trash_ttl in config).
   • Restoring a file does not revert its original name. Use FileManager::update() to rename if needed:

     FileManager::update($fileId, ['name' => 'new-name.jpg']);
     

3. Concurrency Issues

   • File IDs are generated sequentially. In high-traffic apps, race conditions may occur when uploading multiple files simultaneously. Use transactions:

     DB::transaction(function () {
         FileManager::upload($file1);
         FileManager::upload($file2);
     });
     

Debugging

• Log File Paths: Enable debug mode in config to log full file paths:

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

• Check Disk Space: Use Storage::disk('local')->diskUsage() to verify available space before uploads.

Extension Points

1. Custom Storage Engines Override the StorageEngine contract to support non-Laravel storage (e.g., FTP, custom APIs):

   class CustomEngine implements StorageEngine {
       public function upload($file, $directory) { ... }
   }
   

   Register it in the config:

   'engines' => [
       'custom' => Vendor\PackageName\Engines\CustomEngine::class,
   ],
   

2. Validation Rules Extend the default validator by publishing and modifying the rules.php config file:

   'upload' => [
       'max_size' => '10MB',
       'allowed_types' => ['jpg', 'png', 'pdf'],
   ],
   

3. Event Customization Subscribe to the package’s events to add pre/post hooks:

   FileUploaded::subscribe(function ($event) {
       // Send notification, log, etc.
   });