Configuring the Uploading of Image Files

Before uploading files, you must configure the "mappings" for the VichUploaderBundle. These "mappings" tell the bundle where should the files be uploaded and which paths should be used to display them in the application.

This is the configuration needed for this example:

1
2
3
4
5
6
7
8
9
10
11
12

# config/services.yaml
parameters:
    app.path.product_images: /uploads/images/products
    # ...

# config/packages/vich_uploader.yaml
vich_uploader:
    # ...
    mappings:
        product_images:
            uri_prefix:         '%app.path.product_images%'
            upload_destination: '%kernel.project_dir%/public%app.path.product_images%'

The product_images value is a freely chosen name which holds the configuration for a specific mapping. This value will be used later in the entity configuration.

The uploaded images are stored in the directory defined in upload_destination. The uri_prefix option defines the base path prepended to file paths so they can be displayed in the application. In this example, the uri_prefix value is defined as a container parameter, because we'll reuse this value in the EasyAdmin configuration later.

Preparing your Entities to Persist Images

Considering that the Product entity is already created, the first change you need to make is adding the Uploadable annotation to the entity class:

1
2
3
4
5
6
7
8
9
10
11

use Symfony\Component\HttpFoundation\File\File;
use Vich\UploaderBundle\Mapping\Annotation as Vich;

/**
 * @ORM\Entity
 * @Vich\Uploadable
 */
class Product
{
    // ...
}

Then, you need to add two new properties (image and imageFile):

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
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

use Symfony\Component\HttpFoundation\File\File;
use Vich\UploaderBundle\Mapping\Annotation as Vich;

/**
 * @ORM\Entity
 * @Vich\Uploadable
 */
class Product
{
    /**
     * @ORM\Column(type="string", length=255)
     * @var string
     */
    private $image;

    /**
     * @Vich\UploadableField(mapping="product_images", fileNameProperty="image")
     * @var File
     */
    private $imageFile;

    /**
     * @ORM\Column(type="datetime")
     * @var \DateTime
     */
    private $updatedAt;

    // ...

    public function setImageFile(File $image = null)
    {
        $this->imageFile = $image;

        // VERY IMPORTANT:
        // It is required that at least one field changes if you are using Doctrine,
        // otherwise the event listeners won't be called and the file is lost
        if ($image) {
            // if 'updatedAt' is not defined in your entity, use another property
            $this->updatedAt = new \DateTime('now');
        }
    }

    public function getImageFile()
    {
        return $this->imageFile;
    }

    public function setImage($image)
    {
        $this->image = $image;
    }

    public function getImage()
    {
        return $this->image;
    }
}

The image property stores just the name of the uploaded image and it's persisted in the database. The imageFile property stores the binary contents of the image file and it's not persisted in the database (that's why it doesn't define a @ORM annotation).

The imageFile property must define a @Vich\UploadableField annotation that configures both the "mapping" to use (product_images in this case) and the entity property that stores the image name (image in this case).

Displaying the Images in the list and show Views

Use the special image type in the list and show views to display the contents of a property as an image:

1
2
3
4
5
6
7
8
9
10
11
12

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        Product:
            # ...
            list:
                fields:
                    - { property: 'image', type: 'image', base_path: '%app.path.product_images%' }
            # ...
            show:
                fields:
                    - { property: 'image', type: 'image', base_path: '%app.path.product_images%' }

The property used to display the image must be the one that stores the image path (image in this case) and not the one that stores the binary contents of the image (imageFile). Since this property only stores the image name, you must also define the base_path option to prepend the path to make the image accessible.

Instead of hardcoding the base_path value, this example uses the app.path.product_images container parameter which also was used in the VichUploaderBundle configuration.

1
2
3
4
5
6
7
8

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        Product:
            # ...
            list:
                fields:
                    - { property: 'image', template: 'vich_uploader_image.html.twig' }

1
2
3
4
5
6
7
8
9
10

{# templates/vich_uploader_image.html.twig #}
<a href="#" class="easyadmin-thumbnail" data-featherlight="#easyadmin-lightbox-{{ item.id }}" data-featherlight-close-on-click="anywhere">
    {# the second parameter is the name of the property with the UploadableField annotation #}
    <img src="{{ vich_uploader_asset(item, 'imageFile') }}">
</a>

<div id="easyadmin-lightbox-{{ item.id }}" class="easyadmin-lightbox">
    {# the second parameter is the name of the property with the UploadableField annotation #}
    <img src="{{ vich_uploader_asset(item, 'imageFile') }}">
</div>

Uploading the Images in the edit and new Views

The easiest way to enable uploading images in the forms of the edit and new views is to define the type of the property as file:

1
2
3
4
5
6
7
8
9

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        Product:
            # ...
            form:
                fields:
                    - { property: 'imageFile', type: 'file' }
            # ...

In this case, the property must be the one which stores the binary contents of the image (imagefile in this case) and not the one that stores just the name (image in this case).

Although this works as expected, its behavior is too basic (for example you can't see a preview of the existing image before uploading a new file). In order to get the best experience, use VichImageType as the type of the property:

1
2
3
4
5
6
7
8
9

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        Product:
            # ...
            form:
                fields:
                    - { property: 'imageFile', type: 'vich_image' }
            # ...

Configuring the Uploading of Files

Define the "mapping" for the new user contracts:

1
2
3
4
5
6
7
8
9
10
11
12

# config/services.yaml
parameters:
    app.path.user_contracts: /uploads/files/user/contracts
    # ...

# config/packages/vich_uploader.yaml
vich_uploader:
    # ...
    mappings:
        user_contracts:
            uri_prefix: '%app.path.user_contracts%'
            upload_destination: '%kernel.project_dir%/public%app.path.user_contracts%'

Preparing your Entities to Persist Files

Considering that the User entity already exists, add two new properties to store the name of the contract (contract property) and the binary contents of the PDF file (contractFile property). Only the first property is persisted in the database:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\HttpFoundation\File\File;
use Vich\UploaderBundle\Mapping\Annotation as Vich;

/**
 * @ORM\Entity
 * @Vich\Uploadable
 */
class User
{
    /**
     * @ORM\Column(type="string", length=255)
     * @var string
     */
    private $contract;

    /**
     * @Vich\UploadableField(mapping="user_contracts", fileNameProperty="contract")
     * @var File
     */
    private $contractFile;

    // ... getters and setters for these properties
}

Displaying the Files in the list and show Views

This is the most tricky part of adding support for file uploads. Contrary to images, it's not easy to provide a preview of the contents for any kind of file. Instead of trying to do that, we'll display a View contract (PDF) link in the list and show views.

First, add the contract property to the list of properties to display:

1
2
3
4
5
6
7
8
9

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        User:
            # ...
            list:
                fields:
                    # ...
                    - contract

Then, add the template option to define the custom template to use to render the contents of this property:

1
2
3
4
5
6
7
8
9

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        User:
            # ...
            list:
                fields:
                    # ...
                    - { property: 'contract', template: 'contract.html.twig' }

Now you must create the templates/contract.html.twig template with this content:

1

<a href="{{ value }}">View contract (PDF)</a>

Reload your backend and you'll see the link to the contract PDF. However, if you click on the link, you won't see the file. The reason is that the contract property only stores the name of the file, but you also need the public path to that file (which in this case is stored in the app.path.user_contracts parameter).

The solution is simple: you can define any number of arbitrary options for a property and they will be available in your custom template via the field_options option. So you just need to add a new option in the property definition:

1
2
3
4
5

# Before
- { property: 'contract', template: 'contract.html.twig' }

# After
- { property: 'contract', template: 'contract.html.twig', base_path: '%app.path.user_contracts%' }

Then, update the custom template to use this new option:

1

<a href="{{ field_options.base_path ~ '/' ~ value }}">View contract (PDF)</a>

1

<a href="{{ asset(value, 'user_contracts') }}">View contract (PDF)</a>

Uploading the Files in the edit and new Views

Thanks to the custom VichFileType provided by the bundle, this is pretty straightforward:

1
2
3
4
5
6
7
8
9

# config/packages/easy_admin.yaml
easy_admin:
    entities:
        Product:
            # ...
            form:
                fields:
                    - { property: 'contractFile', type: 'vich_file' }
            # ...