Important
You are browsing the documentation for version 3.1 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.
See our Release Process documentation for more information on the currently supported and upcoming releases.
OroAttachmentBundle Configuration¶
Configure Supported Mime Types¶
In the system configuration, under General Setup > Upload Settings, a user can configure supported mime types for files and image fields.
Each mime type should be set from a new line.
A user can set only available mime types from the configuration.
To add or remove available mime types, add changes to the upload_file_mime_types section and upload_image_mime_types in the config.yml file:
1 oro_attachment:
2 upload_file_mime_types:
3 - application/msword
4 - application/vnd.ms-excel
5 - application/pdf
6 - application/zip
7 - image/gif
8 - image/jpeg
9 - image/png
10 upload_image_mime_types:
11 - image/gif
12 - image/jpeg
13 - image/png
File Types¶
File types enable to upload files to any entity.
When creating a new file field type, a user should specify the maximum size of the file supported for this field. On the entity record’s details page, this field is displayed as a link to download this file.
Image Types¶
Image file types enable to upload images to any entity.
When creating a new image field type, a user should specify the maximum size of the file supported for this field as well as its width and height to enable the thumbnail image preview.
On the entity record’s details page, this field is displayed as a thumbnail image with a link to download the original image file.
It can be used with Digital Asset Management (DAM) functionality.
Configure Storage¶
OroAttachmentBundle uses KnpGaufretteBundle to provide a filesystem abstraction layer.
Based on the default configuration, it stores files in var/attachment directory of your project. A user can reconfigure these settings. You can find more information on the KnpGaufretteBundle configuration in the related KnpGaufretteBundle documentation.
Image thumbnail files are created from LiipImagineBundle and are stored in the public/media/cache/attachment directory.
ACL Protection¶
ACL protection provides access to files and images of the entity which they are assigned to. A user should have view permissions to a parent record to be authorized to download the attached files.
Use Migration Extension (Example)¶
It is possible to create an image or a file field via migrations using AttachmentExtension. For example:
1 namespace Acme\Bundle\DemoBundle\Migrations\Schema\v1_0;
2
3 use Doctrine\DBAL\Schema\Schema;
4
5 use Oro\Bundle\AttachmentBundle\Migration\Extension\AttachmentExtension;
6 use Oro\Bundle\AttachmentBundle\Migration\Extension\AttachmentExtensionAwareInterface;
7 use Oro\Bundle\MigrationBundle\Migration\Migration;
8 use Oro\Bundle\MigrationBundle\Migration\QueryBag;
9
10 class AcmeDemoBundle implements Migration, AttachmentExtensionAwareInterface
11 {
12 /** @var AttachmentExtension */
13 protected $attachmentExtension;
14
15 /**
16 * {@inheritdoc}
17 */
18 public function setAttachmentExtension(AttachmentExtension $attachmentExtension)
19 {
20 $this->attachmentExtension = $attachmentExtension;
21 }
22
23 /**
24 * {@inheritdoc}
25 */
26 public function up(Schema $schema, QueryBag $queries)
27 {
28 $this->attachmentExtension->addImageRelation(
29 $schema,
30 'entity_table_name', // entity table, e.g. oro_user, orocrm_contact etc.
31 'new_field_name', // field name
32 [], //additional options for relation
33 7, // max allowed file size in megabytes, can be omitted, by default 1 Mb
34 100, // thumbnail width in pixels, can be omitted, by default 32
35 100 // thumbnail height in pixels, can be omitted, by default 32
36 );
37 }
38 }
Also, you can enable attachments for an entity, e.g.,:
1 namespace Acme\Bundle\DemoBundle\Migrations\Schema\v1_0;
2
3 use Doctrine\DBAL\Schema\Schema;
4 use Oro\Bundle\MigrationBundle\Migration\Migration;
5 use Oro\Bundle\MigrationBundle\Migration\QueryBag;
6 use Oro\Bundle\AttachmentBundle\Migration\Extension\AttachmentExtension;
7 use Oro\Bundle\AttachmentBundle\Migration\Extension\AttachmentExtensionAwareInterface;
8
9 class AcmeDemoBundle implements Migration, AttachmentExtensionAwareInterface
10 {
11 /** @var AttachmentExtension */
12 protected $attachmentExtension;
13
14 /**
15 * {@inheritdoc}
16 */
17 public function setAttachmentExtension(AttachmentExtension $attachmentExtension)
18 {
19 $this->attachmentExtension = $attachmentExtension;
20 }
21
22 /**
23 * {@inheritdoc}
24 */
25 public function up(Schema $schema, QueryBag $queries)
26 {
27 $this->attachmentExtension->addAttachmentAssociation(
28 $schema,
29 'entity_table_name', // entity table, e.g. oro_user, orocrm_contact etc.
30 [], // optional, allowed MIME types of attached files, if empty - global configuration will be used
31 2 // optional, max allowed file size in megabytes, by default 1 Mb
32 );
33 }
34 }
Entity Attachments¶
Configurable entities can use attachments for adding additional files to their records.
To enable attachments for an entity, an administrator should enable them in the current entity configuration.
Additionally, an admin can set array with allowed mine types and maximum sizes of the attached files.
If no mime types were set, the mime types from Upload settings (system configuration) are used for validation.
Once the schema is updated, the Add attachment button becomes available for the current entity.
Image Formatters¶
A user can use 3 formatters for image type fields.
image_encoded returns an image tag with embedded image content in the src attribute. Additional parameters:
alt- a custom alt attribute for the image tag. By default, the original file name is used.height- a custom height attribute for the image tag. There is no default value for this attribute.width- custom width attribute for the image tag. There is no default value for this attribute.
image_link returns a link to the resized image (e.g. <a href='http://test.com/path/to/image.jpg'>image name</a>). Additional parameters:
title- a custom image text value. By default, the original file name is used.height- a custom image height. By default, it is 100 px.width- a custom image width. By default, it is 100 px.
image_src returns the url to the resized image (e.g., http://test.com/path/to/image.jpg). Additional parameters:
height- a custom image height. By default, it is 100 px.width- a custom image width. By default, it is 100 px.
Enable Debugging Images¶
By default, images are processed by the front controller (index_dev.php) in the dev environment. However, you can also enable your web server to process images instead of front controllers. It helps boost performance on all platforms and stability on Windows.
To disable debug images, set the debug_images option to false in the config.yml file:
1 oro_attachment:
2 debug_images: false