Module Files Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require cvepdb-cms/module-files
   

   Publish the module's configuration and migrations:

   php artisan vendor:publish --provider="Cvepdb\Files\FilesServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Cvepdb\Files\FilesServiceProvider" --tag="migrations"
   

   Run migrations:

   php artisan migrate
   

2. Basic Usage Register the module in your CMS's module manager (if applicable) or manually include its routes:

   // In a service provider (e.g., AppServiceProvider)
   Route::middleware(['web'])
        ->prefix('files')
        ->group(base_path('vendor/cvepdb-cms/module-files/src/routes/web.php'));
   

3. First File Upload Use the provided facade or service to handle uploads:

   use Cvepdb\Files\Facades\Files;
   
   $file = Files::upload('path/to/file.pdf', 'user_id_here');
   

   Check the documentation for supported methods (e.g., download(), delete()).

Implementation Patterns

Workflow: File Management

1. Uploading Files

   • Use the Files facade or inject the FilesService into controllers:

     public function store(Request $request) {
         $file = $request->file('document');
         $uploaded = Files::upload($file, auth()->id(), ['type' => 'report']);
     }
     

   • Custom Storage: Override the default disk in config/files.php:

     'disk' => 's3', // or 'local', 'custom_disk'
     

2. Accessing Files

   • Generate signed URLs for downloads:

     $url = Files::getDownloadUrl($fileId);
     

   • Stream files directly:

     return Files::download($fileId, 'custom_filename.pdf');
     

3. File Metadata

   • Attach metadata (e.g., tags, descriptions) via the metadata parameter:

     Files::upload($file, auth()->id(), [
         'metadata' => ['description' => 'Quarterly report', 'tags' => ['finance']]
     ]);
     

   • Retrieve metadata:

     $metadata = Files::getMetadata($fileId);
     

4. Event Handling

   • Listen for file events (e.g., FileUploaded, FileDeleted) in EventServiceProvider:

     protected $listen = [
         'Cvepdb\Files\Events\FileUploaded' => [
             'App\Listeners\LogFileUpload',
         ],
     ];
     

Integration Tips

• Laravel Nova/Panel: Extend the module to add file management to your admin panel.
• APIs: Use the FilesController as a blueprint for custom API endpoints.
• Validation: Leverage the module's built-in validation rules (e.g., file_type, max_size) in Form Requests:

  use Cvepdb\Files\Rules\FileType;
  
  public function rules() {
      return [
          'file' => ['required', new FileType(['pdf', 'docx'])],
      ];
  }
  

Gotchas and Tips

Pitfalls

1. Disk Configuration

   • If using local disk, ensure the storage_path('app/files') directory is writable:

     chmod -R 775 storage/app/files
     

   • For s3, verify credentials in .env and test connectivity:

     php artisan storage:link
     

2. File Ownership

   • The module assumes files are tied to a user ID. If using anonymous uploads, override the FilesService or extend the File model:

     // In a service provider
     $this->app->bind('Cvepdb\Files\Contracts\FilesService', function ($app) {
         return new CustomFilesService($app);
     });
     

3. Large Files

   • Disable chunked uploads for files >100MB by setting:

     'chunked_uploads' => false, // in config/files.php
     

   • Use queues for async processing:

     Files::upload($file, $userId)->afterUpload(function ($file) {
         ProcessLargeFile::dispatch($file);
     });
     

4. Route Conflicts

   • The module registers routes under /files. If conflicts arise, override the route prefix in config/files.php:

     'route_prefix' => 'media',
     

Debugging

• Log Uploads: Enable debug mode in config/files.php:

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

• Check Events: Verify events fire by listening to FileUploaded in Tinker:

  php artisan tinker
  >>> event(new \Cvepdb\Files\Events\FileUploaded($file));
  

Extension Points

1. Custom Storage Drivers Extend the FilesService to support new storage backends:

   namespace App\Services;
   
   use Cvepdb\Files\Contracts\FilesService as BaseFilesService;
   
   class CustomFilesService extends BaseFilesService {
       public function upload($file, $userId, array $options = []) {
           // Custom logic (e.g., encrypt files before upload)
           return parent::upload($file, $userId, $options);
       }
   }
   

2. File Processing Hook into the FileUploaded event to process files (e.g., OCR, thumbnails):

   public function handle(FileUploaded $event) {
       $file = $event->file;
       // Generate thumbnail
       Thumbnail::create($file->path, "thumb_{$file->id}.jpg");
   }
   

3. Model Bindings Bind the File model to routes for easy access:

   Route::get('/files/{file}', function (Cvepdb\Files\Models\File $file) {
       return $file->path;
   });
   

4. Policy Integration Attach policies to the File model for authorization:

   use Cvepdb\Files\Models\File;
   use Illuminate\Auth\Access\HandlesAuthorization;
   
   class FilePolicy {
       use HandlesAuthorization;
   
       public function download(User $user, File $file) {
           return $user->id === $file->user_id;
       }
   }