Symfony UX Cropper.js

Edit this page

Symfony UX Cropper.js is a Symfony bundle integrating the Cropper.js library in Symfony applications. It is part of the Symfony UX initiative.

Installation

Caution

Before you start, make sure you have StimulusBundle configured in your app.

Install the bundle using Composer and Symfony Flex:

1
$ composer require symfony/ux-cropperjs

If you're using WebpackEncore, install your assets and restart Encore (not needed if you're using AssetMapper):

1
2
$ npm install --force
$ npm run watch

Note

For more complex installation scenarios, you can install the JavaScript assets through the @symfony/ux-cropperjs npm package

Configuring the Image Driver

The server-side cropping (Crop::getCroppedImage() and Crop::getCroppedThumbnail()) is powered by Intervention Image. By default it uses the gd driver. You can switch to imagick or vips through the bundle configuration:

1
2
3
# config/packages/cropperjs.yaml
cropperjs:
    driver: gd # "gd" (default), "imagick" or "vips"

The gd and imagick drivers ship with intervention/image (make sure the matching ext-gd or ext-imagick PHP extension is enabled). The vips driver additionally requires the intervention/image-driver-vips package, the libvips system library and the ext-ffi PHP extension:

1
$ composer require intervention/image-driver-vips

Note

The bundle supports intervention/image versions 2, 3 and 4. The driver option requires version 3 or higher: on version 2, only gd and imagick are available, and vips is rejected. Upgrading to version 4 is recommended, as version 2 triggers PHP deprecations.

Using a custom driver

If you need full control over the Intervention Image driver, register your own service implementing Intervention\Image\Interfaces\DriverInterface and reference it with the driver_service option. When set, it takes precedence over driver:

1
2
3
# config/packages/cropperjs.yaml
cropperjs:
    driver_service: App\Image\MyCustomDriver

Note

The driver_service option requires intervention/image version 3 or higher, as version 2 has no DriverInterface.

Usage

To use Symfony UX Cropper.js, inject the CropperInterface service, create a Crop object, and use this object inside a standard form:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
// ...
use Symfony\Component\HttpFoundation\Request;
use Symfony\UX\Cropperjs\Factory\CropperInterface;
use Symfony\UX\Cropperjs\Form\CropperType;

class HomeController extends AbstractController
{
    #[Route('/', name: 'app_homepage')]
    public function index(CropperInterface $cropper, Request $request): Response
    {
        $crop = $cropper->createCrop('/server/path/to/the/image.jpg');
        $crop->setCroppedMaxSize(2000, 1500);

        $form = $this->createFormBuilder(['crop' => $crop])
            ->add('crop', CropperType::class, [
                'public_url' => '/public/url/to/the/image.jpg',
                'cropper_options' => [
                    'aspectRatio' => 2000 / 1500,
                ],
            ])
            ->getForm()
        ;

        $form->handleRequest($request);

        if ($form->isSubmitted() && $form->isValid()) {
            // Get the cropped image data (as a string)
            $crop->getCroppedImage();

            // Create a thumbnail of the cropped image (as a string)
            $crop->getCroppedThumbnail(200, 150);

            // ...
        }

        return $this->render('home/index.html.twig', [
            'form' => $form->createView(),
        ]);
    }
}

These cropper_options can be any the Cropper.js options.

Once created in PHP, a crop form is a normal form, meaning you can display it using Twig as you would normally with any form:

1
{{ form(form) }}

Extend the default behavior

Symfony UX Cropper.js allows you to extend its default behavior using a custom Stimulus controller:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// mycropper_controller.js

import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    connect() {
        this.element.addEventListener('cropperjs:pre-connect', this._onPreConnect);
        this.element.addEventListener('cropperjs:connect', this._onConnect);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side effects
        this.element.removeEventListener('cropperjs:connect', this._onConnect);
        this.element.removeEventListener('cropperjs:pre-connect', this._onPreConnect);
    }

    _onPreConnect(event) {
        // The cropper has not yet been created and options can be modified
        console.log(event.detail.options);
        console.log(event.detail.img);
    }

    _onConnect(event) {
        // The cropper was just created and you can access details from the event
        console.log(event.detail.cropper);
        console.log(event.detail.options);
        console.log(event.detail.img);

        // For instance you can listen to additional events
        event.detail.img.addEventListener('cropend', function () {
            // ...
        });
    }
}

Then in your form, add your controller as an HTML attribute:

1
2
3
4
5
6
7
8
9
10
$form = $this->createFormBuilder(['crop' => $crop])
    ->add('crop', CropperType::class, [
        'public_url' => '/public/url/to/the/image.jpg',
        'cropper_options' => [
            'aspectRatio' => 2000 / 1800,
        ],
        'attr' => ['data-controller' => 'mycropper'],
    ])
    ->getForm()
;

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version