File Distribution Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require aboutcoders/file-distribution-bundle:~1.1
   

   Register the bundle in config/bundles.php (Symfony Flex) or AppKernel.php (legacy):

   return [
       // ...
       Abc\Bundle\FileDistributionBundle\AbcFileDistributionBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Define a filesystem in config/packages/abc_file_distribution.yaml:

   abc_file_distribution:
       db_driver: orm
       filesystems:
           local:
               type: local
               path: '%kernel.project_dir%/public/uploads'
           s3:
               type: s3
               bucket: my-bucket
               key: '%env(AWS_KEY)%'
               secret: '%env(AWS_SECRET)%'
   

3. First Use Case: Uploading a File Inject the FileDistributionManager service and use it to upload:

   use Abc\Bundle\FileDistributionBundle\Manager\FileDistributionManager;
   
   class MyController {
       public function __construct(private FileDistributionManager $fileManager) {}
   
       public function upload(Request $request) {
           $file = $request->file('file');
           $path = $this->fileManager->upload($file, 'local', 'user_uploads');
           return new Response("File uploaded to: $path");
       }
   }
   

Implementation Patterns

Core Workflows

1. Filesystem Abstraction Use the bundle to switch between storage backends (local, S3, FTP) without changing business logic:

   // Upload to S3
   $this->fileManager->upload($file, 's3', 'profile_pictures');
   
   // Upload to local filesystem (fallback)
   $this->fileManager->upload($file, 'local', 'backups');
   

2. File Distribution Copy files between filesystems (e.g., local → CDN):

   $this->fileManager->distribute('local', 'cdn', 'user_uploads/file.jpg');
   

3. Symfony Integration

   • Twig Integration: Use the abc_file_distribution.twig extension to generate URLs:

     {{ abc_file_distribution_url('cdn', 'user_uploads/file.jpg') }}
     

   • Form Types: Extend Abc\Bundle\FileDistributionBundle\Form\Type\FileType for custom file handling.

4. Event-Driven Workflows Listen to file events (e.g., post-upload processing):

   // config/services.yaml
   services:
       App\EventListener\FileUploadListener:
           tags:
               - { name: 'kernel.event_listener', event: 'abc_file_distribution.upload', method: 'onUpload' }
   

Best Practices

• Configuration: Prefer environment variables for sensitive data (e.g., AWS_KEY).
• Naming Conventions: Use consistent filesystem names (e.g., local, s3, cdn) across the app.
• Fallback Logic: Define a default filesystem in config for graceful degradation:

  abc_file_distribution:
      default_filesystem: local
  

Gotchas and Tips

Pitfalls

1. Doctrine ORM Dependency

   • The bundle defaults to Doctrine ORM. If using MongoDB/Propel, ensure the db_driver is correctly set and the underlying AbcFileDistribution library supports your ODM.
   • Fix: Verify the AbcFileDistribution library’s documentation for supported persistence layers.

2. Filesystem Permissions

   • Local filesystems require proper directory permissions (e.g., chmod -R 775 public/uploads).
   • Tip: Use umask in your deployment script to avoid permission issues.

3. S3/CDN Configuration

   • Misconfigured AWS credentials or bucket policies can cause silent failures.
   • Debugging: Enable Symfony’s monolog handler for Abc\Bundle\FileDistributionBundle to log errors:

     monolog:
         handlers:
             abc_file_distribution:
                 type: stream
                 path: "%kernel.logs_dir%/file_distribution.log"
                 level: debug
     

4. File Path Handling

   • Paths are relative to the filesystem’s root. Hardcoding absolute paths (e.g., /var/www/uploads) will break portability.
   • Tip: Use the path key in configuration for local filesystems and let the bundle handle resolution.

Debugging Tips

• Check Filesystem Existence:

  if (!$this->fileManager->hasFilesystem('nonexistent')) {
      throw new \RuntimeException('Filesystem not configured');
  }
  

• Validate Uploads: Use the validate() method to check file constraints before upload:

  $this->fileManager->validate($file, [
      'maxSize' => '10M',
      'mimeTypes' => ['image/jpeg', 'image/png'],
  ]);
  

Extension Points

1. Custom Filesystem Types Extend the Abc\FileDistribution\Filesystem\FilesystemInterface to support new backends (e.g., Google Cloud Storage):

   class GcsFilesystem implements FilesystemInterface {
       // Implement required methods
   }
   

   Register it as a service and configure it in abc_file_distribution.yaml.

2. Pre/Post-Processing Use event subscribers to modify files before/after operations:

   // Example: Resize images on upload
   public function onUpload(FileUploadEvent $event) {
       if ($event->getFilesystem()->getName() === 'local') {
           $event->getFile()->resize(new \Imagick(), 800, 600);
       }
   }
   

3. Custom Metadata Extend the File entity to store additional metadata (e.g., alt_text for images):

   // src/Entity/File.php
   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $altText;
   

   Update the bundle’s mapping configuration to include the new field.