presta/image-bundle

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

PrestaImageBundle

, _(*1)

Overview

PrestaImageBundle is a Symfony bundle providing tools to resize uploaded and remote images before sending them through a classic form. It uses the Cropper.js library., _(*2)

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation., _(*3)

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:, _(*4)

$ composer require presta/image-bundle

Applications that don't use Symfony Flex

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the following command to download the latest stable version of this bundle:, _(*5)

$ composer require presta/image-bundle

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles in the config/bundles.php file of your project:, _(*6)

// config/bundles.php

return [
    // ...
    Presta\ImageBundle\PrestaImageBundle::class => ['all' => true],
];

Configuration

You must configure the form_layout.html.twig form theme into config/packages/twig.yaml., _(*7)

twig:
    form_themes:
        - "@PrestaImage/form/form_layout.html.twig"

Note: you can also create your own form theme instead., _(*8)

You must include the routing into config/routes.yaml:, _(*9)

presta_image:
    resource: "@PrestaImageBundle/config/routing.yaml"

See VichUploader documentation to configure the bundle., _(*10)

Assets

See Cropper.js documentation to install assets., _(*11)

Don't forget to include the following assets in your page:, _(*12)

• @PrestaImageBundle/public/css/cropper.css
• @PrestaImageBundle/public/js/cropper.js

How to: implementation examples

• Webpack Encore

Usage

Initialize cropper

document.querySelectorAll('.presta-image').forEach(element => {
    new Cropper(element)
})

Use the form type

<?php

use Presta\ImageBundle\Form\Type\ImageType;

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

Available options for the ImageType:, _(*13)

• 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): CSS class of the "upload" button (default: '')
• cancel_button_class (string): CSS class of the "cancel" button (default: '')
• save_button_class (string): CSS class of the "save" button (default: '')
• download_uri (string): the path where the image is located (default: null, automatically set)
• show_image (bool): whether the image should be rendered in the form or not (default: true)
• file_upload_enabled (bool): whether to enable the file upload widget or not (default: true)
• remote_url_enabled (bool): whether to enable the remote url widget or not (default: true)
• rotation_enabled (bool): whether to enable the rotation or not (default: false)
• 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)

Notes

You can find Cropper.js options [here][5]., _(*14)

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., _(*15)

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

Contributing

Pull requests are welcome., _(*17)

Thanks to everyone who has contributed already., _(*18)

This project is supported by PrestaConcept, _(*19)

Lead Developer : @J-Ben87, _(*20)

Released under the MIT License, _(*21)