Files Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require arxy/files
   

2. Basic Configuration Add to config/packages/arxy_files.yaml:

   arxy_files:
       managers:
           default:
               driver: orm
               class: 'App\Entity\File'
               storage: 'public'
               naming_strategy: 'Arxy\FilesBundle\NamingStrategy\SplitHashStrategy'
               repository: 'App\Repository\FileRepository'
   

3. Create File Entity Extend \Arxy\FilesBundle\Entity\File:

   namespace App\Entity;
   use Doctrine\ORM\Mapping as ORM;
   use Arxy\FilesBundle\Entity\File as BaseFile;
   
   #[ORM\Entity]
   class File extends BaseFile { ... }
   

4. First Upload

   use Arxy\FilesBundle\ManagerInterface;
   
   public function uploadFile(Request $request, ManagerInterface $manager)
   {
       $file = $request->files->get('file');
       $fileEntity = $manager->upload($file);
       // Persist via Doctrine orm
   }
   

Implementation Patterns

Core Workflows

1. File Upload & Persistence

   • Use ManagerInterface for uploads:

     $manager->upload($splFileInfo); // Returns File entity
     

   • Doctrine listeners handle file system operations on postPersist/preRemove.

2. Embedded Files

   • Use EmbeddableFile for lightweight file references:

     #[ORM\Embedded(class: EmbeddableFile::class)]
     private ?EmbeddableFile $thumbnail;
     

3. Form Integration

   • Use FileType for Symfony forms:

     $builder->add('document', FileType::class, [
         'input_options' => ['attr' => ['accept' => 'application/pdf']]
     ]);
     

4. File Serving

   • Direct Download:

     return $downloadUtility->createResponse($fileEntity);
     

   • CDN/URL Generation:

     $pathResolver->getPath($fileEntity); // Returns filesystem path
     

Advanced Patterns

1. Custom Naming Strategies

   • Decorate existing strategies (e.g., AppendExtensionStrategy):

     $naming = new AppendExtensionStrategy(new SplitHashStrategy());
     

2. LiipImagine Integration

   • Use FileFilterPathResolver for dynamic image paths:

     $resolver->getUrl(new FileFilter($file, 'thumbnail'));
     

3. Event-Driven Workflows

   • Extend DoctrineORMListener for custom logic:

     $listener = new CustomFileListener($manager);
     // Register with Doctrine
     

Gotchas and Tips

Common Pitfalls

1. Double Uploads

   • Use md5Hash for deduplication. Files with identical hashes reuse storage.

2. File Persistence Timing

   • Files are not moved to storage until the entity is persisted. Use postPersist listeners.

3. Naming Strategy Conflicts

   • Ensure strategies return unique paths. Test with SplitHashStrategy first.

4. Doctrine ORM Only

   • Currently, only Doctrine ORM is supported. For other DBALs, extend RepositoryInterface.

Debugging Tips

1. Check File Paths

   • Log paths via namingStrategy->getPath($file) to verify structure.

2. Verify Storage Adapter

   • Confirm FlySystem adapters (e.g., Local, S3) are configured correctly.

3. Listener Registration

   • Ensure DoctrineORMListener is tagged in services:

     tags:
         - { name: doctrine.event_listener, event: postPersist }
     

Extension Points

1. Custom Storage Backends

   • Implement StorageInterface for non-FlySystem storage (e.g., database blobs).

2. Validation Rules

   • Extend FileType constraints:

     $builder->add('file', FileType::class, [
         'constraints' => [new File\MaxSize('10M')]
     ]);
     

3. Path Normalization

   • Override PathResolver for custom URL schemes (e.g., CDN prefixes).

Configuration Quirks

• Default Manager: Always define a default manager in arxy_files.yaml.
• FlySystem Storage: Ensure flysystem config matches the manager’s storage key.
• Embedded Files: Use EmbeddableFile for lightweight references (avoids full entity overhead).