File Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dahovitech/file-manager-bundle
   

   Add to config/bundles.php:

   Dahovitech\FileManagerBundle\FileManagerBundle::class => ['all' => true],
   

2. Publish Configuration

   php bin/console dahovitech:file-manager:install
   

   This generates:

   • config/packages/dahovitech_file_manager.yaml (default config)
   • Migrations for database tables (if using DB storage)
   • Assets for frontend JS/CSS

3. First Use Case: Basic Upload Inject the FileManagerService in a controller:

   use Dahovitech\FileManagerBundle\Service\FileManagerService;
   
   public function upload(Request $request, FileManagerService $fileManager)
   {
       $file = $request->file('file');
       $result = $fileManager->upload($file, [
           'folder' => 'uploads',
           'allowed_types' => ['image/jpeg', 'image/png'],
       ]);
       return $result->getUrl(); // Returns public URL
   }
   

4. Frontend Integration Include the bundle's JS in your template:

   {{ dahovitech_file_manager('upload_widget', {
       'target_folder': 'uploads',
       'allowed_types': ['image/*', 'application/pdf'],
       'max_size': '10MB'
   }) }}
   

Implementation Patterns

Core Workflows

1. File Upload Patterns

• Single File Upload

  $result = $fileManager->upload($file, [
      'folder' => 'documents',
      'rename' => true, // Auto-generate filename
      'overwrite' => false,
  ]);
  

• Chunked Upload (for large files)

  // Start chunked upload
  $chunkId = $fileManager->startChunkedUpload($file, [
      'folder' => 'large_files',
      'chunk_size' => '5MB',
  ]);
  
  // Resume later
  $fileManager->resumeChunkedUpload($chunkId, $nextChunk);
  

• Drag & Drop Handler Configure the frontend widget to emit events:

  document.getElementById('upload-widget').addEventListener('file-uploaded', (e) => {
      console.log('File uploaded:', e.detail.fileId);
  });
  

2. File Organization

• Folder Navigation

  $folders = $fileManager->getFolders('root', [
      'depth' => 2, // Limit to 2 levels deep
      'filter' => ['type' => 'image'],
  ]);
  

• Tagging System

  $fileManager->addTagsToFile($fileId, ['project', '2024']);
  $files = $fileManager->searchFiles(['tags' => ['project']]);
  

• Breadcrumb Generation

  {{ dahovitech_file_manager('breadcrumb', {
      'current_path': 'projects/2024/q1'
  }) }}
  

3. Image Processing

• Thumbnail Generation

  $thumbnails = $fileManager->generateThumbnails($fileId, [
      'sizes' => ['100x100', '300x300', '800x600'],
      'format' => 'webp',
      'quality' => 80,
  ]);
  

• EXIF Data Extraction

  $exifData = $fileManager->getExifData($fileId);
  // Returns array with GPS, camera model, etc.
  

4. Multi-Storage Integration

• Switch Storage Providers Configure in config/packages/dahovitech_file_manager.yaml:

  dahovitech_file_manager:
      default_storage: s3
      storages:
          local:
              driver: local
              root: '%kernel.project_dir%/public/uploads'
          s3:
              driver: aws
              key: '%env(AWS_KEY)%'
              secret: '%env(AWS_SECRET)%'
              bucket: 'my-app-files'
              region: 'eu-west-1'
  

  Use in code:

  $fileManager->upload($file, ['storage' => 's3']);
  

Integration Tips

Symfony Forms

Extend the bundle's FileType for form integration:

use Dahovitech\FileManagerBundle\Form\Type\FileManagerType;

$builder->add('document', FileManagerType::class, [
    'label' => 'Project Document',
    'folder' => 'projects',
    'allowed_types' => ['application/pdf'],
    'max_size' => '20MB',
]);

API Endpoints

Create a custom API controller:

use Dahovitech\FileManagerBundle\Service\FileManagerService;

class FileManagerApiController extends AbstractController
{
    public function upload(FileManagerService $fileManager, Request $request): JsonResponse
    {
        $file = $request->files->get('file');
        $result = $fileManager->upload($file, $request->request->all());

        return $this->json([
            'url' => $result->getUrl(),
            'file_id' => $result->getId(),
        ]);
    }
}

Event Listeners

Listen to file events (e.g., post-upload):

use Dahovitech\FileManagerBundle\Event\FileUploadedEvent;

public function onFileUpload(FileUploadedEvent $event)
{
    $file = $event->getFile();
    // Add custom logic (e.g., log, notify, process)
}

Register in services.yaml:

services:
    App\EventListener\FileManagerListener:
        tags:
            - { name: kernel.event_listener, event: dahovitech.file.uploaded, method: onFileUpload }

Gotchas and Tips

Common Pitfalls

1. Storage Configuration Mismatch

   • Issue: Files disappear after upload.
   • Fix: Verify default_storage in config matches your setup. For local storage, ensure the root directory is writable:

     chmod -R 775 %kernel.project_dir%/public/uploads
     

2. Chunked Upload Failures

   • Issue: Large files fail with "Incomplete chunks" errors.
   • Fix: Ensure session.save_path is configured and has sufficient disk space. For production, use database-backed sessions:

     framework:
         session:
             handler_id: symfony.session.handler.doctrine
     

3. Frontend Widget Not Loading

   • Issue: Upload widget shows blank or errors.
   • Fix: Check:
     • Assets are published (php bin/console assets:install).
     • Webpack Encore is configured (if using custom builds).
     • No JS errors in browser console (clear cache if needed).

4. Permission Denied on AWS S3

   • Issue: Uploads to S3 fail silently.
   • Fix: Validate IAM permissions. Ensure the bucket policy allows:

     {
         "Version": "2012-10-17",
         "Statement": [
             {
                 "Effect": "Allow",
                 "Principal": "*",
                 "Action": ["s3:PutObject", "s3:GetObject"],
                 "Resource": "arn:aws:s3:::my-app-files/*"
             }
         ]
     }
     

5. Thumbnail Generation Failing

   • Issue: Thumbnails return false or corrupt images.
   • Fix: Install required PHP extensions:

     pecl install imagick
     

     Or use gd as fallback:

     dahovitech_file_manager:
         image_driver: gd
     

Debugging Tips

1. Enable Verbose Logging Add to config/packages/dev/dahovitech_file_manager.yaml:

   dahovitech_file_manager:
       debug: true
   

   Check logs at var/log/dev.log for detailed upload/storage operations.

2. Validate File Metadata Use the inspect method to debug file issues:

   $metadata = $fileManager->inspect($file);
   // Returns size, mime, path, etc.
   

3. Database Storage Quirks If using database storage:

   • Ensure LOBS are enabled in your DB (PostgreSQL/MySQL).
   • Monitor files table size; large binaries may bloat the DB.

Extension Points

1. Custom Storage Drivers Implement Dahovitech\FileManagerBundle\Storage\StorageInterface:

   class CustomStorage implements StorageInterface
   {
       public function save(File $file, string $path): FileResult
       {
           // Custom logic (e.g., FTP, Google Cloud)
       }
       // Implement other methods...
   }
   

   Register in config:

   dahovite