README

Overview

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

Installation

Require the bundle as a Composer dependency

composer require presta/image-bundle

Configure the bundle

You must use the bootstrap_4.html.twig form theme into config/packages/twig.yaml.

twig:
    form_themes:
        - "@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 config/routes.yaml:

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

See VichUploader documentation to configure the bundle.

Install assets

See Cropper documentation to install assets.

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
/path/to/cropper/dist/jquery-cropper.min.js
@PrestaImageBundle/Resources/public/css/cropper.css
@PrestaImageBundle/Resources/public/js/cropper.js

Note that jQuery and Bootstrap are required and must be included.

How to: implementation examples

Webpack Encore

Usage

Initialize cropper

(function(w, $) {

    'use strict';

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

})(window, jQuery);

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:

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)

Notes

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!

Contributing

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

prolixlib / image-bundle

Maintainers

Details