Foto Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require antwebes/foto-bundle
   

   Ensure your composer.json includes "symfony/framework-bundle": ">=2.1" (or equivalent for Symfony 2.x).

2. Enable the Bundle Add to app/AppKernel.php:

   new Antwebes\FotoBundle\AntwebesFotoBundle(),
   

3. Configure VichUploader Update config.yml:

   vich_uploader:
       db_driver: orm
       storage: file_system
       mappings:
           foto:
               uri_prefix: /uploads/images
               upload_destination: '%kernel.project_dir%/web/uploads/images'
               namer: Vich\UploaderBundle\Naming\SmartUniqueNamer
   

4. First Use Case: Uploading an Image Create an entity (e.g., Product) with a FotoType field:

   use Antwebes\FotoBundle\Entity\Foto;
   use Doctrine\ORM\Mapping as ORM;
   
   /**
    * @ORM\Entity
    */
   class Product {
       /**
        * @ORM\OneToOne(targetEntity="Foto", mappedBy="product")
        */
       private $foto;
   }
   

   Use the FotoType form in your controller:

   use Antwebes\FotoBundle\Form\Type\FotoType;
   
   $form = $this->createForm(FotoType::class, $product);
   

Implementation Patterns

Workflow: Image Management

1. Entity Setup Extend Foto entity or embed it in your model:

   class Article {
       /**
        * @ORM\OneToOne(targetEntity="Antwebes\FotoBundle\Entity\Foto", cascade={"persist"})
        * @Assert\Valid
        */
       private $coverImage;
   }
   

2. Form Integration Use FotoType in your form builder:

   $builder->add('coverImage', FotoType::class, [
       'label' => 'Cover Image',
       'required' => false,
       'allow_file_replace' => true, // Enable file replacement
   ]);
   

3. Handling Uploads In your controller, handle the form submission:

   $form->handleRequest($request);
   if ($form->isSubmitted() && $form->isValid()) {
       $em->persist($product);
       $em->flush();
       // FotoBundle auto-handles uploads via VichUploader
   }
   

4. Displaying Images Use the foto_image Twig filter:

   <img src="{{ product.coverImage.pathAndUrl }}"/>
   

   Or access the path directly:

   $imagePath = $product->getCoverImage()->getPath();
   

Integration Tips

• Custom Naming: Override the namer in config.yml for unique filenames:

  mappings:
      foto:
          namer: App\Namer\CustomNamer
  

• Validation: Add constraints to FotoType:

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

• Batch Processing: Use FotoManager for bulk operations:

  $manager = $this->get('antwebes_foto.manager');
  $manager->deleteAllImagesForEntity($product);
  

Gotchas and Tips

Pitfalls

1. Symfony 2.x Compatibility

   • The bundle targets Symfony 2.1–2.2-dev. Avoid using with Symfony 3+ or 4+ without forks.
   • Fix: Use a compatible fork (e.g., vich/uploader-bundle) if migrating.

2. File Permissions

   • Ensure web/uploads/images is writable:

     chmod -R 775 %kernel.project_dir%/web/uploads/images
     

   • Debug: Check vich_uploader.log for permission errors.

3. Missing Documentation

   • The index.rst lacks details on advanced features (e.g., custom storage).
   • Workaround: Refer to VichUploaderBundle docs for gaps.

4. Entity Lifecycle

   • Delete Behavior: Files are not auto-deleted when entities are removed. Fix: Implement preRemove in your entity:

     public function preRemove() {
         $this->getCoverImage()->remove();
     }
     

Debugging

• Upload Failures: Check:
  • var/log/dev.log for VichUploader exceptions.
  • Browser console for 500 errors (often permission-related).
• Path Issues: Verify uri_prefix in config.yml matches your web root.

Extension Points

1. Custom Storage Override the storage handler in services.yml:

   services:
       antwebes_foto.storage:
           class: App\Storage\S3Storage
           arguments: ['@aws_sdk.s3']
   

2. Event Listeners Subscribe to vich_uploader.upload events for post-upload logic:

   services:
       app.foto_listener:
           class: App\EventListener\FotoListener
           tags:
               - { name: kernel.event_listener, event: vich_uploader.upload, method: onUpload }
   

3. Twig Extensions Extend the foto_image filter for custom processing:

   class FotoExtension extends \Twig_Extension {
       public function getFilters() {
           return [
               new \Twig_SimpleFilter('resize_foto', [$this, 'resizeImage']),
           ];
       }
   }