presta/image-bundle

PrestaImageBundle is a Symfony bundle providing tools to resize uploaded and remote images before sending them through a classic form.

Installs: 95 302

Dependents: 0

Suggesters: 1

Security: 0

Stars: 18

Watchers: 8

Forks: 18

Open Issues: 2

Language:Twig

Type:symfony-bundle

v2.4.0 2022-04-29 14:14 UTC

README

Build Status Scrutinizer Code Quality Latest Stable Version Total Downloads

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.

Installation

Make sure Composer is installed globally, as explained in the installation chapter of the Composer documentation.

Applications that use Symfony Flex

Open a command console, enter your project directory and execute:

$ 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:

$ 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:

// 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.

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

Note: you can also create your own 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.

Assets

See Cropper.js documentation to install assets.

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

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

How to: implementation examples

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:

  • 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: '')
  • cancel_button_class (string): class of the button (default: '')
  • save_button_class (string): class of the button (default: '')
  • 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 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.

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 easily be manipulated client side. ALWAYS validate the image-data, image-size, image-format 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