Allow to crop local and remote image before uploading them through a classic form.

Installs: 34 516

Dependents: 1

Suggesters: 1

Security: 0

Stars: 12

Watchers: 6

Forks: 15

Open Issues: 2


v1.10.1 2019-02-18 15:46 UTC


Build Status Scrutinizer Code Quality Latest Stable Version Total Downloads


PrestaImageBundle is a Symfony bundle providing tools to resize local/remote images before uploading them through a classic form. It uses Cropper jQuery plugin.


Require the bundle as a Composer dependency

composer require presta/image-bundle

Enable the bundles in the kernel

You must add the following bundles into app/AppKernel.php:


public function registerBundles()
    $bundles = [
        // ...
        new Vich\UploaderBundle\VichUploaderBundle(),
        new Presta\ImageBundle\PrestaImageBundle(),

Configure the bundle

You must use the bootstrap_4.html.twig form theme into app/config.yml.

        - "@PrestaImage/form/bootstrap_4.html.twig"

Note: you can also use the bootstrap_3.html.twig form theme instead.

You must include the routing into app/config/routing.yml:

    resource: "@PrestaImageBundle/Resources/config/routing.yml"

See VichUploader documentation to configure the bundle.

Install assets

See Cropper quick start section to install assets.

Note that jQuery and Bootstrap are required.

Don't forget to include the following assets in your page:

  • /path/to/cropper/dist/cropper.min.css
  • /path/to/cropper/dist/cropper.min.js
  • @PrestaImageBundle/Resources/public/css/cropper.css
  • @PrestaImageBundle/Resources/public/js/cropper.js

How to: implementation examples


Initialize cropper

(function(w, $) {

    'use strict';

    $(function() {
        $('.cropper').each(function() {
            new Cropper($(this));

})(window, jQuery);

Use the form type


use Presta\ImageBundle\Form\Type\ImageType;

public function buildForm(FormBuilderInterface $builder, array $options)
        ->add('image', ImageType::class)

Available options for the ImageType:

  • aspect_ratios (array): a list of aspect ratio to apply when resizing an image
  • cropper_options (array): a list of options supported by cropper (default: ['autoCropArea' => 1])
  • max_width (int): the max width of the cropped image send to server (default: 320)
  • max_height (int): the max height of the cropped image send to server (default: 180)
  • preview_width (string): the max width to use when displaying the image preview - can be in px, % or other css value (default: '320px')
  • preview_height (string): the max height to use when displaying the image preview - can be in px, % or other css value (default: '180px')
  • upload_button_class (string): class of the button (default: 'btn btn-sm btn-primary')
  • upload_button_icon (string): class of the button (default: 'fa fa-upload')
  • cancel_button_class (string): class of the button (default: 'btn btn-default')
  • save_button_class (string): class of the button (default: 'btn btn-primary')
  • download_uri (string): the path where the image is located (default: null, automatically set)
  • download_link (bool): whether the end user should be able to add a remote image by URL (default: true)
  • enable_locale (bool): whether to enable the locale upload (default: true)
  • enable_remote (bool): whether to enable the remote upload (default: true)
  • upload_mimetype (string): format of the image to be uploaded (default: image/png)
    (Note: If the chosen mimetype is not supported by the browser, it will silently fall back to image/png)
  • upload_quality (float): quality (0..1) of uploaded image for lossy imageformats (eg. image/jpeg) (default: 0.92)


You can find Cropper options here.

The max_width and max_height options are used to define maximum size the cropped uploaded image will be. Bigger images (after cropping) are scaled down.

Security Note: NEVER rely on this size constraints and the format settings as they can be easily manipulated client side. ALWAYS validate the image-data, -size, -format at server side!


Pull requests are welcome.

Thanks to everyone who has contributed already.

This project is supported by PrestaConcept

Lead Developer : @J-Ben87

Released under the MIT License