Download the PHP package ethsam/symfony-dropzone without Composer

Symfony Dropzone Bundle

Seamless integration of Dropzone.js into Symfony Forms with automatic entity relationship management for drag-and-drop file uploads.

ES

Features

• Drag-and-drop file uploads — Powered by Dropzone.js
• Entity relationship support — Automatically manage OneToMany and ManyToOne associations
• Built-in data transformation — IDs to entities via Doctrine ORM
• Pre-populated edit forms — Show existing files in edit mode
• Fully configurable — Dropzone.js options exposed in form builder
• Single or multiple files — Control upload mode per form field
• Custom upload/remove handlers — Route-based endpoints with JSON responses
• Image resizing — Client-side image processing before upload
• Flexible authentication — Custom headers for API integration
• Symfony Flex compatible — Automatic bundle registration

Requirements

• PHP: ≥8.1
• Symfony: 5.4, 6.x, 7.x
• Doctrine ORM: 2.12+
• Dropzone.js: 6.0+ (included via CDN)

Installation

Step 1: Install via Composer

The bundle registers automatically with Symfony Flex. If you're not using Flex, add to config/bundles.php:

Step 2: Include Dropzone.js

Add the following to your base template (e.g., base.html.twig):

That's it! You're ready to use DropzoneType in your forms.

Quick Start

1. Define Your File Entity

2. Define Your Main Entity with Relationship

3. Create a Form Type

4. Create Upload/Remove Handlers

5. Use the Form in Your Template

That's it! The bundle handles everything:

• Dropzone.js widget rendering
• File upload via AJAX
• File ID storage in hidden fields
• Entity relationship transformation on form submission

Configuration Options

File Entity Requirements

Your file/attachment entity must implement:

• getId(): ?int — Returns the unique identifier
• getFilename(): string — Returns the filename for display
• Getter for choice_src property — By default getSrc(): string, returns the file URL/path for thumbnail display

Example minimal entity:

How It Works

Architecture Overview

1. Form Type Registration — DropzoneType extends Symfony's form system
2. Hidden Fields — For multiple files: a CollectionType with hidden inputs; for single: an EntityType field
3. Twig Template — Renders Dropzone.js widget with JavaScript configuration
4. Upload Flow:
   • User drags files or clicks to select
   • Dropzone.js sends each file to your uploadHandler route via AJAX
   • Handler persists entity to database, returns {"id": <int>}
   • Bundle stores file ID in hidden form field
5. Form Submission — Hidden field values are collected
6. Data Transformation — DropzoneTransformer converts IDs back to entity objects via Doctrine
7. Persistence — Form submission handles OneToMany/ManyToOne relationships automatically

File Removal Flow

1. User clicks "Remove" link on file preview
2. Dropzone.js sends DELETE (or POST) to removeHandler route
3. Handler deletes entity, returns {"id": <int>}
4. Widget removes preview from DOM
5. On next form submission, removed ID is not included, relationship is updated

Examples

Basic Multiple File Upload

Single File Upload (ManyToOne)

Image-Only with Custom Dimensions

With Custom Headers (API Authentication)

Custom Preview Container

With Custom Form Data

Your upload handler receives this in $request->request->all():

Upgrading from v1

If you're upgrading from the original emr-dev/symfony-dropzone:

• Bundle namespace changed — Ethsam\SymfonyDropzone (was EmrDev\SymfonyDropzoneBundle)
• Form type import — Update: use Ethsam\SymfonyDropzone\Form\DropzoneType;
• Option names — No changes; all options are backward compatible
• PHP requirement — Now requires PHP ≥8.1
• Symfony support — Now supports Symfony 5.4, 6.x, 7.x
• Data transformer — Automatic; no manual entity conversion needed

Migration example:

The API and functionality remain the same.

Differences from symfony/ux-dropzone

Summary: Use ethsam/symfony-dropzone for entity-driven file management; use symfony/ux-dropzone if you need tight Stimulus integration or prefer the UX paradigm.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m "feat: add your feature"
4. Push to the branch: git push origin feat/your-feature
5. Open a Pull Request

For bug reports or feature requests, please open an issue.

License

This bundle is licensed under the MIT License. See LICENSE for details.

Originally forked from emr-dev/symfony-dropzone.

Credits

• Samuel Etheve — Current maintainer
• Emomaliev M. — Original author (emr-dev/symfony-dropzone)
• Dropzone.js — File upload library