Imagecrop Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Ensure LiipImagineBundle and VichUploaderBundle are installed and configured in your Symfony 2.8+ app.

   composer require liip/imagine-bundle vich/uploader-bundle
   

2. Bundle Registration Add to config/bundles.php:

   Anacona16\ImageCropBundle\Anacona16ImageCropBundle::class => ['all' => true],
   

3. First Use Case Extend a form type to enable cropping:

   use Anacona16\ImageCropBundle\Form\Type\ImageCropType;
   
   $builder->add('image', ImageCropType::class, [
       'label' => 'Profile Image',
       'required' => false,
       'crop' => true, // Enable cropping
       'scale' => 0.8, // Optional: Scale factor (0-1)
   ]);
   

4. Template Integration Use the provided Twig extension to render the cropper:

   {{ form_widget(form.image) }}
   {{ form_row(form.image) }}
   {% if form.image.vars.crop %}
       {{ form_widget(form.image.crop) }}
   {% endif %}
   

Implementation Patterns

Workflow: Upload + Crop

1. Form Submission Handle uploads via VichUploaderBundle (e.g., preUpload, postUpload events).

   // In your entity
   use Vich\UploaderBundle\Mapping\Annotation as Vich;
   
   #[Vich\Uploadable]
   class User {
       #[Vich\UploadableField(mapping: 'user_images', appDir: 'app/')]
       private $image;
   }
   

2. Crop Processing Configure LiipImagineBundle filters for cropping (e.g., crop, thumbnail).

   # config/packages/liip_imagine.yaml
   liip_imagine:
       filter_sets:
           crop_user:
               quality: 75
               filters:
                   crop: { dimensions: [200, 200], position: [0, 0] }
   

3. Form Integration Use ImageCropType with crop and scale options:

   $builder->add('image', ImageCropType::class, [
       'crop' => true,
       'scale' => 0.9,
       'crop_filter' => 'crop_user', // Link to LiipImagine filter
   ]);
   

4. Validation Validate cropped dimensions in your controller:

   $form->handleRequest($request);
   if ($form->isSubmitted() && $form->isValid()) {
       $image = $form->get('image')->getData();
       if ($image && $image->getCrop()) {
           $cropData = $image->getCrop();
           // Validate $cropData->getWidth(), $cropData->getHeight()
       }
   }
   

Integration Tips

• Dynamic Filters: Use crop_filter to dynamically apply different cropping rules per entity.
• Preview Generation: Generate previews in postUpload events using LiipImagineBundle.
• Asset Management: Store cropped images in a dedicated directory (configured in vich_uploader).

Gotchas and Tips

Pitfalls

1. Deprecated Bundle

   • Issue: The bundle is unmaintained (last release 2017). Use Symfony UX CropperJS for modern projects.
   • Workaround: Fork the repo or patch locally if critical for legacy systems.

2. VichUploader Dependency

   • Issue: Requires VichUploaderBundle for file handling. Conflicts may arise if not configured properly.
   • Fix: Ensure vich_uploader is set up with correct mappings and storage paths.

3. Crop Data Persistence

   • Issue: Crop coordinates (position, dimensions) are not automatically saved to the database.
   • Fix: Manually persist crop data in your entity or use a custom field type.

4. LiipImagine Filters

   • Issue: Misconfigured filters (e.g., wrong crop dimensions) may corrupt images.
   • Debug: Test filters in isolation using liip:imagine:filter:dump.

Debugging

• Check Uploads: Verify files are uploaded via VichUploaderBundle logs (debug:config vich_uploader).
• Crop Data: Dump crop data in the controller to validate:

  dump($form->get('image')->getData()->getCrop());
  

• Twig Errors: Ensure imagecrop Twig extension is registered in services.yaml:

  services:
      Anacona16\ImageCropBundle\Twig\ImageCropExtension:
          tags: ['twig.extension']
  

Extension Points

1. Custom Crop Logic Extend Anacona16\ImageCropBundle\Form\Type\ImageCropType to add validation or processing:

   class CustomImageCropType extends ImageCropType {
       public function configureOptions(OptionsResolver $resolver) {
           $resolver->setDefaults([
               'custom_option' => false,
           ]);
       }
   }
   

2. Event Listeners Hook into vich_uploader.post_upload to process cropped images:

   // src/EventListener/CropListener.php
   public function onPostUpload(UploadEvent $event) {
       $image = $event->getUploadable();
       if ($image->getCrop()) {
           // Apply custom crop logic
       }
   }
   

3. Asset Pipelines Integrate with Webpack Encore or Symfony AssetMapper for modern asset handling if using legacy JS/CSS from the bundle.