File Manager Bundle Laravel Package

Getting Started

Minimal Setup

1. Install via Composer

   composer require akyos/file-manager-bundle
   

2. Enable the Bundle Add to config/bundles.php:

   return [
       // ...
       Akyos\FileManagerBundle\AkyosFileManagerBundle::class => ['all' => true],
   ];
   

3. Configure Storage Update config/packages/akyos_file_manager.yaml (or create it):

   akyos_file_manager:
       storage:
           path: '%kernel.project_dir%/public/uploads'  # Default upload directory
           adapter: 'local'  # Options: 'local', 's3', 'gcs'
           # S3/GCS config (if applicable)
           # aws:
           #     key: '%env(AWS_KEY)%'
           #     secret: '%env(AWS_SECRET)%'
           #     bucket: 'my-bucket'
   

4. First Use Case: Upload a File Use the FileManager service in a controller:

   use Akyos\FileManagerBundle\Service\FileManager;
   
   public function uploadFile(Request $request, FileManager $fileManager)
   {
       $file = $request->file('file');
       $path = $fileManager->upload($file, 'user_uploads'); // 'user_uploads' = subdirectory
       return response()->json(['path' => $path]);
   }
   

Where to Look First

• Service API: src/Service/FileManager.php – Core methods (upload, delete, getUrl, listFiles).
• Configuration: config/packages/akyos_file_manager.yaml – Storage backends and defaults.
• Twig Extension: src/Twig/FileManagerExtension.php – For template-based file operations (e.g., {{ file_manager.getUrl(file) }}).

Implementation Patterns

Common Workflows

1. File Upload with Validation

use Symfony\Component\HttpFoundation\File\UploadedFile;

public function handleUpload(UploadedFile $file, FileManager $fileManager)
{
    // Validate file type/size
    if (!$file->isValid() || $file->getClientOriginalExtension() !== 'pdf') {
        throw new \RuntimeException('Invalid file');
    }

    // Upload with custom path
    $path = $fileManager->upload($file, 'documents/' . uniqid());
    return $this->redirectToRoute('download', ['path' => $path]);
}

2. Generating Public URLs

// In a controller or Twig template
$url = $fileManager->getUrl('documents/report.pdf'); // Returns full public URL

3. Listing Files in a Directory

$files = $fileManager->listFiles('user_uploads');
foreach ($files as $file) {
    echo $file->getPath(); // e.g., 'user_uploads/123.pdf'
}

4. Deleting Files

$fileManager->delete('user_uploads/123.pdf');

Integration Tips

• Symfony Forms: Use FileType with custom validation:

  $builder->add('file', FileType::class, [
      'mapped' => false,
      'constraints' => [new File(['maxSize' => '1024k', 'mimeTypes' => ['application/pdf']])],
  ]);
  

• Event Listeners: Extend file operations via events (if the bundle supports them; check EventDispatcher integration).
• APIs: Return file URLs in JSON responses:

  return $this->json(['downloadUrl' => $fileManager->getUrl($path)]);
  

Gotchas and Tips

Pitfalls

1. Permissions Issues

   • Ensure the storage.path directory is writable by the web server:

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

   • For Docker, mount the volume with correct permissions.

2. Missing Configuration

   • If using s3/gcs, all required env vars must be set (e.g., AWS_KEY, AWS_SECRET). The bundle does not fall back to defaults.

3. Relative vs. Absolute Paths

   • getUrl() returns a public URL (e.g., /uploads/file.pdf). Use getAbsolutePath() for filesystem operations:

     $absolutePath = $fileManager->getAbsolutePath('file.pdf');
     

4. No Built-in Thumbnails

   • The bundle handles uploads/deletion but does not generate thumbnails. Use a separate library (e.g., intervention/image) if needed.

Debugging Tips

• Check Logs: Enable debug mode (APP_DEBUG=1) to see storage adapter errors.
• Verify File Existence:

  if (!$fileManager->exists('file.pdf')) {
      throw new \RuntimeException('File not found');
  }
  

• Test Locally First: Use the local adapter before migrating to S3/GCS.

Extension Points

1. Custom Storage Adapters

   • Implement Akyos\FileManagerBundle\Storage\StorageInterface to add support for new backends (e.g., Azure Blob).

2. File Naming Strategies

   • Override the default naming logic (e.g., uuid()) by extending FileManager and injecting a custom FileNamer service.

3. Events (If Supported)

   • Listen for file.uploaded or file.deleted events (check the bundle’s Event classes for details).

4. Twig Filters

   • Extend FileManagerExtension to add custom Twig filters (e.g., {{ file_manager.getThumbnailUrl(file) }}).

Pro Tips

• Use Subdirectories: Organize files by entity/type (e.g., users/{id}/profile.jpg).
• Cache URLs: Store getUrl() results in cache if files are static.
• Cleanup Old Files: Schedule a cron job to delete files not referenced in your DB (e.g., via listFiles() + delete()).