presta / image-bundle
PrestaImageBundle is a Symfony bundle providing tools to resize uploaded and remote images before sending them through a classic form.
Installs: 134 431
Dependents: 0
Suggesters: 1
Security: 0
Stars: 23
Watchers: 9
Forks: 19
Open Issues: 2
Type:symfony-bundle
Requires
- php: ^8.1
- ext-fileinfo: *
- ext-json: *
- symfony/form: ^5.4|^6.4|^7.0
- vich/uploader-bundle: ^2.0
Requires (Dev)
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^9.6
- symfony/phpunit-bridge: ^7.0
- symplify/easy-coding-standard: ^12.0
This package is auto-updated.
Last update: 2024-12-04 18:28:28 UTC
README
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/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/public/css/cropper.css
@PrestaImageBundle/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 imagecropper_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 toimage/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