Laravel Filex Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require devwizardhq/laravel-filex
   php artisan vendor:publish --provider="DevWizardHQ\Filex\FilexServiceProvider" --tag="filex-config"
   php artisan migrate
   

   • Publishes config (config/filex.php) and migrations (creates filex_uploads and filex_quarantined_files tables).

2. Basic Blade Usage:

   <x-filex::upload
       name="documents"
       endpoint="{{ route('filex.upload') }}"
       max-files="5"
       max-file-size="10MB"
       accepted-files="image/*,.pdf,.docx"
   />
   

   • Ensure you have a route for handling uploads:

     Route::post('/filex/upload', [FilexController::class, 'upload'])->name('filex.upload');
     

3. First Use Case:

   • Create a form with <x-filex::upload> and handle submissions via FilexController (auto-generated by the package). The package handles:
     • Temporary storage during upload.
     • Chunked uploads for large files.
     • Progress tracking via JavaScript events.

Implementation Patterns

Core Workflows

1. Drag-and-Drop Integration:

   • Use the Blade component (<x-filex::upload>) with customizable attributes:

     <x-filex::upload
         name="avatars"
         endpoint="{{ route('filex.upload') }}"
         max-files="1"
         preview-template="filex::preview.image" <!-- Custom preview for images -->
         chunk-size="5MB"
     />
     

   • Preview Templates: Extend the package’s default previews (e.g., resources/views/vendor/filex/preview/image.blade.php) for custom file types (PDFs, videos).

2. Chunked Uploads:

   • Configure chunk size in config/filex.php:

     'chunk' => [
         'size' => '10MB', // Default chunk size
         'enabled' => true,
     ],
     

   • Handle chunked uploads in your controller by extending FilexController:

     public function upload(Request $request)
     {
         $upload = (new FilexUploadHandler())->handle($request);
         return response()->json($upload);
     }
     

3. Form Submission:

   • Use finalize() to move temporary files to permanent storage:

     public function store(Request $request)
     {
         $request->validate(['documents' => 'required|array']);
         $upload = Filex::finalize($request->documents);
         // Save $upload->files() to your model
     }
     

4. Quarantine System:

   • Automatically scans uploaded files for malware/viruses (requires config/filex.scanner.enabled = true).
   • Review quarantined files via:

     $quarantined = Filex::quarantined()->latest()->get();
     

Integration Tips

• Laravel Nova/Panel: Use the FilexField trait to integrate uploads into admin panels:

  use DevWizardHQ\Filex\Nova\FilexField;
  
  FilexField::make('Cover Image')->onlyOnDetail(),
  

• Validation: Extend validation rules:

  use DevWizardHQ\Filex\Rules\Filex;
  
  $request->validate([
      'files' => ['required', new Filex(['max' => 5, 'types' => 'image/jpeg'])]
  ]);
  

• Storage: Override default storage (e.g., S3) in config/filex.php:

  'storage' => [
      'disk' => 's3',
      'path' => 'uploads/{year}/{month}',
  ],
  

Gotchas and Tips

Pitfalls

1. Temporary Files:

   • Files are stored temporarily in storage/app/filex/temp/ until finalize() is called. Never rely on these files persisting beyond the request.
   • Fix: Always call Filex::finalize() in your form submission logic.

2. Chunked Upload Failures:

   • If chunks fail mid-upload, the package marks files as "incomplete." Check for these in the database (filex_uploads table) and retry:

     $incomplete = Filex::uploads()->where('status', 'incomplete')->get();
     

   • Tip: Implement a queue job to retry failed chunks:

     Filex::retryUpload($uploadId);
     

3. CSRF Token:

   • Ensure your upload endpoint includes @csrf in Blade or passes the token via JavaScript:

     Dropzone.options.myDropzone = {
         headers: { 'X-CSRF-TOKEN': '{{ csrf_token() }}' }
     };
     

4. Scanner Conflicts:

   • If using a third-party scanner (e.g., ClamAV), ensure the filex.scanner.command in config points to the correct binary. Test locally first:

     php artisan filex:scan --path=/path/to/test/file
     

Debugging

• Log Upload Events: Enable debug mode in config/filex.php:

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

  • Logs appear in storage/logs/laravel.log.

• Check Database:

  • filex_uploads: Tracks all upload sessions.
  • filex_quarantined_files: Lists flagged files.
  • Tip: Use Tinker to inspect:

    php artisan tinker
    >>> \DevWizardHQ\Filex\Models\Upload::all();
    

Extension Points

1. Custom Events:

   • Listen for upload events (e.g., Filex\Events\UploadStarted):

     Filex::listen(function ($event) {
         Log::info('Upload started', $event->upload->toArray());
     });
     

2. Override Blade Components:

   • Publish and modify the Blade views:

     php artisan vendor:publish --tag="filex-views"
     

   • Edit resources/views/vendor/filex/upload.blade.php for custom UI.

3. Add File Types:

   • Extend the Filex facade to support new file types (e.g., 3D models):

     Filex::extend('3d-model', function ($file) {
         return new \App\Services\ThreeDModel($file);
     });
     

4. API Integration:

   • Use the FilexUploadHandler directly in API routes:

     public function apiUpload(Request $request)
     {
         $handler = new \DevWizardHQ\Filex\Handlers\FilexUploadHandler();
         return response()->json($handler->handle($request));
     }
     

Configuration Quirks

• Disk Permissions: Ensure storage/app/filex/ is writable:

  chmod -R 775 storage/app/filex
  

• Memory Limits: Large chunked uploads may hit PHP’s memory_limit. Increase it in .env:

  MEMORY_LIMIT=2G
  

• Queue Workers: For async processing (e.g., scanning), run:

  php artisan queue:work