Upload Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require backend2-plus/upload-bundle
   

2. Configure Flysystem Add filesystem adapters and filesystems in config/packages/oneup_flysystem.yaml:

   oneup_flysystem:
       adapters:
           public_uploads:
               local:
                   directory: '%kernel.project_dir%/public/upload'
       filesystems:
           public_uploads_filesystem:
               adapter: public_uploads
   

3. First Upload Use the provided API endpoint:

   POST /api/upload
   

   With a multipart/form-data request containing a file.

4. Service Injection Inject UploadService in your controller/service:

   use Backend2Plus\UploadBundle\Service\UploadService;
   
   public function __construct(private UploadService $uploadService) {}
   

Implementation Patterns

Core Workflow

1. Single File Upload

   $file = $request->file('file');
   $uploadedFile = $this->uploadService->upload($file, 'public_uploads_filesystem');
   return $uploadedFile->getUrl(); // Returns the accessible URL
   

2. Multiple File Upload Use MultipleUploadBundleService:

   $files = $request->files->all();
   $uploadedFiles = $this->multipleUploadService->uploadMultiple($files, 'public_uploads_filesystem');
   return array_map(fn($file) => $file->getUrl(), $uploadedFiles);
   

3. File Validation Extend validation via UploadService:

   $this->uploadService->upload($file, 'public_uploads_filesystem', [
       'allowed_mime_types' => ['image/jpeg', 'image/png'],
       'max_size' => 5 * 1024 * 1024, // 5MB
   ]);
   

Integration with Doctrine

• MediaObject Entity The bundle assumes an existing MediaObject entity. Ensure it’s mapped to the filesystem:

  // Example MediaObject mapping
  /**
   * @ORM\Column(type="string")
   */
  private $path;
  
  /**
   * @ORM\Column(type="string")
   */
  private $url;
  

• Post-Upload Logic Attach metadata to MediaObject after upload:

  $mediaObject = new MediaObject();
  $mediaObject->setPath($uploadedFile->getPath());
  $mediaObject->setUrl($uploadedFile->getUrl());
  $mediaObject->setMimeType($uploadedFile->getMimeType());
  $entityManager->persist($mediaObject);
  

API Endpoint Customization

Override the default /api/upload endpoint by:

1. Creating a custom controller extending UploadController.
2. Configuring routing in config/routes.yaml:

   upload:
       path: /custom/upload
       controller: App\Controller\CustomUploadController::upload
   

Gotchas and Tips

Pitfalls

1. Filesystem Permissions Ensure directories (public/upload, privatePictures) are writable by the web server:

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

2. MediaObject Entity Mismatch The bundle expects a MediaObject entity with path, url, and mimeType fields. Verify your entity matches:

   // If missing, add:
   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $mimeType;
   

3. Flysystem Adapter Conflicts Avoid naming conflicts with existing adapters/filesystems in oneup_flysystem.yaml.

4. Deprecated Service Namespace Old code using App\Bundles\Upload\MultipleUploadBundleService must update to the new namespace:

   // Old (deprecated)
   use App\Bundles\Upload\MultipleUploadBundleService;
   
   // New
   use Backend2Plus\UploadBundle\Service\App\Bundles\Upload\MultipleUploadBundleService;
   

Debugging

• Upload Failures Check Symfony’s ProblemDetails response for errors (e.g., invalid MIME type, size limit). Enable debug mode to log filesystem issues:

  # config/packages/dev/oneup_flysystem.yaml
  oneup_flysystem:
      debug: true
  

• File Path Resolution Use UploadService::getFilesystem() to inspect the active filesystem:

  $filesystem = $this->uploadService->getFilesystem('public_uploads_filesystem');
  $filesystem->listContents('/'); // Debug contents
  

Extension Points

1. Custom Storage Adapters Extend Flysystem adapters (e.g., S3) by adding to oneup_flysystem.yaml:

   adapters:
       s3_uploads:
           aws:
               bucket: 'my-bucket'
               region: 'us-east-1'
   

2. Pre/Post-Upload Hooks Subscribe to events (if the bundle supports them) or wrap UploadService:

   $uploadedFile = $this->uploadService->upload($file, 'fs');
   $this->postUploadLogic($uploadedFile); // Custom logic
   

3. Validation Rules Dynamically set rules via dependency injection:

   # config/services.yaml
   Backend2Plus\UploadBundle\Service\UploadService:
       arguments:
           $defaultValidationRules:
               allowed_mime_types: ['image/*']
               max_size: 10MB