Skip to content

Alles für WordPress, Webentwicklung — und mehr

📤 Datei-Upload mit Drag & Drop mit Dropzone.js und PHP
Webentwicklung
10 Min1,908 Wörter

📤 Datei-Upload mit Drag & Drop mit Dropzone.js und PHP

Anwender erwarten, Dateien auf eine Website hochladen zu können, indem sie diese einfach in das Browserfenster ziehen. Der Button „Datei auswählen" und der Datei-Explorer gelten bereits als überflüssige Schritte. Drag-and-Drop jedoch von Grund auf in JavaScript zu programmieren, bedeutet mehrere hundert Zeilen Code, Fortschrittsbalken, Vorschauen und Fehlerbehandlung. Glücklicherweise gibt es eine fertige Bibliothek, die all das out of the box abdeckt.

Dropzone.js ist eine Open-Source-JavaScript-Bibliothek für Datei-Uploads per Drag-and-Drop. Sie zeigt Bildvorschauen und einen Fortschrittsbalken an und benötigt kein jQuery. Sie funktioniert mit jeder serverseitigen Sprache: PHP, Node.js, Python. In dieser Anleitung finden Sie den vollständigen Zyklus von der Installation bis zur Produktivumgebung in sechs Schritten.

💡 Kurzüberblick:

  • Was sie leistet: Die Bibliothek Dropzone.js verwandelt ein beliebiges HTML-Element in eine Ablagezone für Dateien mit AJAX-Übermittlung an den Server.
  • Installation: ein CDN-Link (unpkg oder jsDelivr) oder ein npm-Paket; beide Optionen werden im ersten Schritt behandelt.
  • Serverseitige Verarbeitung: ein PHP-Skript empfängt die Datei über $_FILES, genau wie bei einem normalen Formular; der dritte Schritt enthält einsatzbereiten Code.
  • Einsatzbereiche: Kontaktformulare mit Anhängen, Avatar-Uploads, Massenimport von Bildern in eine WordPress-Galerie.

Schritt 1: Dropzone.js installieren

Der schnellste Weg ist die Einbindung der Bibliothek per CDN. Fügen Sie diesen Tag in den <head> Ihrer Seite ein:

1<script src="https://unpkg.com/dropzone@5/dist/min/dropzone.min.js"></script>

Die CSS-Datei wird separat eingebunden:

1<link rel="stylesheet" href="https://unpkg.com/dropzone@5/dist/min/dropzone.min.css" />

Falls Sie einen Bundler verwenden, installieren Sie das Paket via npm:

1npm install dropzone

Und importieren Sie es in Ihrer JS-Datei:

1import Dropzone from "dropzone";

Beachten Sie, dass Version 5.9 der letzte stabile Release mit Stand Anfang 2026 ist. Version sechs befindet sich im Beta-Status und wird für den Produktiveinsatz noch nicht empfohlen. Das Projekt-Repository befindet sich nun unter github.com/dropzone/dropzone (zuvor enyo/dropzone).

Schritt 2: Grundlegendes HTML-Markup und Initialisierung

Erstellen Sie ein Formular mit der Klasse dropzone. Dropzone erkennt es automatisch und wandelt es in eine Ablagezone um:

1<form action="/upload.php"
2      class="dropzone"
3      id="my-dropzone"></form>

Das ist alles. Wenn ein Anwender eine Datei in dieses Formular zieht, sendet die Bibliothek sie per AJAX-Request an die URL im action-Attribut. Serverseitig kommt die Datei in $_FILES['file'] an, genau wie bei einer regulären Übermittlung über <input type="file">.

Entwickler schreibt Code für Datei-Uploads

Falls Sie eine Rückfalllösung für Browser ohne JavaScript benötigen, fügen Sie ein reguläres Feld im Formular ein:

1<form action="/upload.php" class="dropzone">
2  <input name="file" type="file" multiple />
3</form>

Die Schaltfläche „Datei auswählen" wird nur angezeigt, wenn JavaScript nicht verfügbar ist. Bei aktiviertem JS blendet Dropzone sie aus und zeigt seine eigene Dropzone an.

Schritt 3: Dateiverarbeitung auf dem Server

Ein PHP-Skript empfängt Uploads auf dieselbe Weise wie ein reguläres Formular. Hier die minimal funktionsfähige Version:

1<?php
2if (!empty($_FILES)) {
3    $uploadDir = __DIR__ . '/uploads/';
4 
5    if (!is_dir($uploadDir)) {
6        mkdir($uploadDir, 0755, true);
7    }
8 
9    $originalName = basename($_FILES['file']['name']);
10    $targetPath   = $uploadDir . time() . '_' . $originalName;
11 
12    if (move_uploaded_file($_FILES['file']['tmp_name'], $targetPath)) {
13        http_response_code(200);
14        echo json_encode(['status' => 'ok', 'file' => $targetPath]);
15    } else {
16        http_response_code(500);
17        echo json_encode(['status' => 'error', 'message' => 'Failed to save file']);
18    }
19}

Was hier passiert:

  • Das Skript erstellt einen uploads/-Ordner, falls dieser nicht existiert.
  • time() wird dem ursprünglichen Dateinamen vorangestellt, was Namenskonflikte verhindert.
  • basename() entfernt jegliche Path-Traversal-Angriffe (Versuche, den Ordner mittels ../ zu verlassen).
  • Dropzone erwartet HTTP 200 vom Server; andernfalls betrachtet es den Upload als fehlgeschlagen und zeigt einen Fehler an.

Für den Produktiveinsatz ergänzen Sie eine Validierung der Dateiendung und des MIME-Typs:

1$allowed = ['jpg', 'jpeg', 'png', 'gif', 'pdf', 'zip'];
2$ext = strtolower(pathinfo($originalName, PATHINFO_EXTENSION));
3 
4if (!in_array($ext, $allowed)) {
5    http_response_code(400);
6    echo json_encode(['status' => 'error', 'message' => 'Invalid file type']);
7    exit;
8}

Schritt 4: Begrenzung von Anzahl, Größe und Typ der Dateien

Die drei am häufigsten benötigten Dropzone-Einstellungen werden über eine JavaScript-Konfiguration vorgenommen:

1Dropzone.options.myDropzone = {
2  maxFiles: 10,
3  maxFilesize: 5,          // In megabytes
4  acceptedFiles: 'image/*,.pdf',
5  dictDefaultMessage: 'Drag files here or click to select'
6};

Erläuterung der Optionen:

  • maxFiles: wie viele Dateien der Nutzer auf einmal hochladen kann. Standardmäßig gibt es kein Limit; im Beispiel nicht mehr als 10.
  • maxFilesize: maximale Größe einer einzelnen Datei in Megabyte. Ein Wert von 5 bedeutet 5 MB. In älteren Bibliotheksversionen war der Standard 256 MB; in der aktuellen 5.x ist er ebenfalls 256, geben Sie daher explizit Ihr eigenes Limit vor.
  • acceptedFiles: eine durch Kommas getrennte Zeichenkette von MIME-Typen. Das Muster image/* erlaubt beliebige Bilder, .pdf fügt PDF zur Liste hinzu. Die vollständige Liste der MIME-Typen finden Sie in der Dropzone-Dokumentation.
  • dictDefaultMessage: der Text, den der Nutzer in der leeren Upload-Zone sieht (in diesem Beispiel Englisch).

Der Schlüssel myDropzone in Dropzone.options.myDropzone ist die CamelCase-Version des HTML-Attributs id="my-dropzone". Bindestriche entfallen und jedes nachfolgende Wort wird großgeschrieben: my-dropzone → myDropzone, file-upload-area → fileUploadArea.

Die Optionen resizeWidth und resizeHeight erlauben es Ihnen, Bilder vor dem Senden clientseitig zu verkleinern. Das spart Bandbreite des Nutzers und reduziert die Serverlast, insbesondere wenn Besucher Handyfotos von jeweils 10-15 MB hochladen. Geben Sie beide Parameter gemeinsam an:

1Dropzone.options.myDropzone = {
2  resizeWidth: 1200,
3  resizeHeight: 1200,
4  resizeQuality: 0.8,
5  resizeMethod: 'contain'
6};

Die Methode contain passt das Bild ohne Zuschnitt in die vorgegebenen Grenzen ein, während crop auf exakte Maße zuschneidet. Eine Qualität von 0.8 ist vom Original praktisch nicht zu unterscheiden, reduziert die Dateigröße jedoch um das 4- bis 7-Fache. Wichtig: die Größenänderung funktioniert nur bei Bilddateien; PDFs und Archive werden unverändert durchgereicht. Der Browser führt die Größenänderung über die Canvas-API durch, sodass keine zusätzlichen Bibliotheken erforderlich sind.

Schritt 5: Manuelles Absenden von Dateien

Standardmäßig sendet Dropzone eine Datei sofort nach dem Hinzufügen an den Server. Das ist nicht immer praktisch: manchmal müssen Sie dem Nutzer ermöglichen, Formularfelder neben der Upload-Zone auszufüllen und alles mit einer einzigen Schaltfläche abzusenden.

Deaktivieren Sie den automatischen Upload mit dem Flag autoProcessQueue: false und binden Sie das Absenden an eine externe Schaltfläche:

1Dropzone.options.myDropzone = {
2  autoProcessQueue: false,
3  maxFilesize: 5,
4  init: function () {
5    const myDropzone = this;
6    const submitBtn = document.querySelector('#btnUpload');
7 
8    submitBtn.addEventListener('click', function () {
9      if (myDropzone.getQueuedFiles().length === 0) {
10        alert('No files to upload');
11        return;
12      }
13      myDropzone.processQueue();
14    });
15 
16    this.on('success', function (file, response) {
17      console.log('File uploaded:', file.name);
18    });
19  }
20};

Der entscheidende Punkt hier ist die Methode processQueue(). Sie stößt das Absenden aller in der Warteschlange gesammelten Dateien an. Das Ereignis success wird für jede Datei einzeln ausgelöst, sodass Sie die Oberfläche aktualisieren oder die ID der hochgeladenen Datei in einem versteckten Formularfeld speichern können.

Schritt 6: Zusätzliche Daten zusammen mit der Datei senden

Manchmal müssen Sie einem Upload Service-Parameter mitgeben: Nutzer-ID, Dokumentenstatus, ausgewählte Kategorie. Dropzone bietet dafür das Ereignis sending:

1Dropzone.options.myDropzone = {
2  init: function () {
3    this.on('sending', function (file, xhr, formData) {
4      formData.append('status', 'draft');
5      formData.append('user_id', currentUserId);
6    });
7 
8    this.on('success', function (file, responseText) {
9      console.log('Done:', responseText);
10    });
11  }
12};

Das Ereignis sending wird unmittelbar vor dem Absenden des XMLHttpRequest aufgerufen. Das dritte Argument formData ist ein standardmäßiges FormData-Objekt, dem Sie über append() beliebige Schlüssel-Wert-Paare hinzufügen können. Serverseitig werden diese Parameter aus $_POST['status'] und $_POST['user_id'] ausgelesen.

Praktisches Szenario: der Nutzer wählt ein Album aus einem Dropdown neben der Dropzone-Fläche aus, und die Album-ID wird mit jeder Datei mitgesendet. Der Server sortiert die Uploads sofort in die entsprechenden Ordner ein.

Sicherheit: drei Regeln, die Sie nicht ignorieren dürfen

Bevor Sie Dropzone produktiv einsetzen, prüfen Sie drei Dinge.

Erstens. Validieren Sie Dateityp und -größe immer serverseitig, auch wenn Sie acceptedFiles und maxFilesize bereits in JS konfiguriert haben. Clientseitige Beschränkungen lassen sich in einer Minute über die Browser-Konsole umgehen. Die serverseitige Filterung ist der einzige echte Schutz.

Zweitens. Speichern Sie hochgeladene Dateien außerhalb des Document Root oder in einem Ordner mit deaktivierter Skriptausführung. Zum Beispiel diese Struktur:

1/public_html        ← document root ( index.php )
2/uploads            ← folder with uploaded files (outside web access)

Dann funktioniert eine direkte URL zur Datei nicht; der Browser liefert die Datei nur über ein PHP-Vermittlungsskript aus, das die Zugriffsrechte prüft.

Drittens. Generieren Sie eindeutige Dateinamen auf dem Server. Vertrauen Sie nicht dem Namen, den der Client sendet: Er kann ../, Null-Bytes oder Sonderzeichen enthalten. basename() + time() + eine Zufallszeichenkette ist das Minimum.

Viertens. Prüfen Sie den Dateiinhalt, nicht nur die Endung. Ein Angreifer kann shell.php in photo.jpg umbenennen und so einen pathinfo()-Filter umgehen. Ein verlässlicher Ansatz: Ermitteln Sie den tatsächlichen MIME-Typ mit finfo_file() (dem eingebauten PHP-Fileinfo-Modul) und gleichen Sie ihn mit einer Whitelist ab. Prüfen Sie bei Bildern zusätzlich, ob getimagesize() gültige Dimensionen liefert; das filtert beschädigte Dateien und getarnte Skripte heraus. Bei Projekten mit hohem Traffic sollten Sie erwägen, Uploads in einen separaten Microservice hinter einem Reverse-Proxy auszulagern, der den Stream entgegennimmt, mit einem Virenscanner (zum Beispiel ClamAV) prüft und ihn erst dann an die Hauptanwendung weiterleitet.

Das kurze Demo-Video oben zeigt den gesamten Prozess in Aktion: HTML-Markup, PHP-Handler und das Ergebnis im Browser in drei Minuten.

⁉️🤔 Häufig gestellte Fragen

Funktioniert Dropzone.js ohne jQuery?

Ja, die Bibliothek ist vollständig unabhängig von jQuery. Ab Version 5.x wurden alle Abhängigkeiten entfernt; siehe den Installationsabschnitt auf dropzone.dev. Es gibt jedoch einen separaten jQuery-Wrapper für diejenigen, die $('.dropzone').dropzone() bevorzugen; dieser befindet sich im selben npm-Paket unter dist/min/dropzone-jquery.min.js.

Wie ändere ich den Fehlertext, wenn eine Datei zu groß ist?

Verwenden Sie die Option dictFileTooBig. Beispiel: dictFileTooBig: 'File is too big. Maximum size is {{maxFilesize}} MB'. Der Platzhalter {{maxFilesize}} fügt automatisch den Wert aus Ihrer Konfiguration ein. Die vollständige Liste der Dict-Schlüssel für die Lokalisierung finden Sie in der Dokumentation.

Können Dateien bei großen Datenmengen in Teilen hochgeladen werden?

Ja, Dropzone v5 bietet integrierte Unterstützung für segmentierte Uploads über die Optionen chunking: true, chunkSize (in Bytes) und forceChunking. Der Server muss in der Lage sein, die Segmente wieder zusammenzusetzen: Empfangen Sie jedes Stück mit den Headern dzchunkindex und dztotalchunkcount, speichern Sie es temporär und führen Sie die Teile nach dem Empfang des letzten zusammen. Ein fertiges PHP-Beispiel für die Segmentzusammenführung ist im Dropzone-Repository verfügbar.

Wie entferne ich eine Dateivorschau nach einem erfolgreichen Upload?

Rufen Sie myDropzone.removeFile(file) im success-Event-Handler auf. Die Datei verschwindet aus der Oberfläche, bleibt aber auf dem Server. Wenn Sie sie auch vom Server löschen müssen, fügen Sie im selben Handler vor removeFile eine AJAX-Anfrage hinzu.

Ist Dropzone mit WordPress kompatibel?

Ja, die Bibliothek kann über wp_enqueue_script() in Ihrem Theme oder Plugin eingebunden werden. Ein typisches WordPress-Szenario: das Ersetzen des Standard-Medien-Uploaders auf einer benutzerdefinierten Admin-Seite oder in einem Frontend-Formular. Sie müssen lediglich die korrekte Handler-URL angeben, normalerweise admin_url('admin-ajax.php') mit einer registrierten AJAX-Aktion.

Ist Dropzone.js das Richtige für Ihr Projekt

Wenn Sie Drag-and-Drop-Dateiuploads „hier und jetzt" benötigen, löst Dropzone.js die Aufgabe schneller als jeder eigene Code. Hier sind fünf Gründe, warum die Bibliothek auch 2026 relevant bleibt:

  • Keine Abhängigkeiten. Kein jQuery, Bootstrap oder React. Eine JS-Datei einbinden, und es funktioniert.
  • Browserübergreifende Unterstützung. Unterstützt Browser bis hinunter zu IE11 und degradiert ohne JavaScript auf elegante Weise.
  • Fertige Visualisierung. Bildvorschauen, Fortschrittsbalken, Erfolgs-/Fehlersymbole direkt einsatzbereit, ohne CSS-Layout-Arbeit.
  • Dokumentation. Aktuelles GitBook und ein aktives GitHub-Repository (über 1.700 Sterne Stand 2026).
  • Flexibilität. Von einfacher Bildgrößenänderung vor dem Upload bis hin zu segmentierten Uploads gigabytegroßer Dateien ist alles konfigurierbar.

Wann Dropzone nicht die beste Wahl ist: wenn Sie bereits React/Vue verwenden und eine native Komponente ohne externe DOM-Manipulation wünschen. Das React-Ökosystem hat react-dropzone, Vue hat vue-dropzone. Aber für Vanilla-JavaScript-, jQuery-Projekte und WordPress-Seiten ist Dropzone.js ein bewährtes Werkzeug, das Sie nicht im Stich lässt.

Praktisches Integrationsbeispiel. Ein typisches WordPress-Szenario: eine Seite „Dokumente hochladen" in einem Kundenportal. Der Nutzer zieht Scans von Reisepass, Vertrag und Immobilienfotos hinein. Dropzone wird über wp_enqueue_script() in der functions.php des Themes eingebunden, und der Handler ist eine benutzerdefinierte AJAX-Aktion, registriert über wp_ajax_nopriv_. Jede erfolgreich hochgeladene Datei wird über wp_insert_attachment() zur Medienbibliothek hinzugefügt, und ihre ID wird in den Benutzer-Meta gespeichert. Der gesamte Frontend-Code passt in 30 Zeilen, die Serverseite in 50. Zum Vergleich: Ein eigenes Drag-and-Drop mit denselben Fähigkeiten würde 400 bis 600 Zeilen JavaScript und 2 bis 3 Tage Entwicklung erfordern.

Was Alternativen betrifft: Uppy (von den Machern von Transloadit) bietet eine modulare Architektur mit Plugins für React, Svelte und S3-Uploads, erfordert aber mehr Abhängigkeiten und Konfiguration. Fine Uploader wird seit 2018 nicht mehr gepflegt; es gibt Forks, jedoch ohne Sicherheitsgarantien. Dropzone.js gewinnt bei der Balance aus „Funktionen pro Komplexitätseinheit": eine Datei, minimale Konfiguration und sichtbare Ergebnisse fünf Minuten nach der Integration.

Einige weitere Fähigkeiten, die Sie kennen sollten, bevor Sie beginnen. Dropzone bietet einen vollständigen Event-Zyklus: addedfile, thumbnail, uploadprogress, complete und queuecomplete. Letzteres ist besonders nützlich: Es wird ausgelöst, wenn alle Dateien in der Warteschlange verarbeitet wurden, und ermöglicht es Ihnen, dem Nutzer eine Zusammenfassung anzuzeigen oder auf eine andere Seite weiterzuleiten. Bei Netzwerkfehlern gibt es eine integrierte Wiederholungsfunktion: Bei einem Upload-Fehler zeigt Dropzone eine Schaltfläche „Wiederholen" neben der Dateivorschau an, und der erneute Versuch läuft über denselben Handler ohne Code-Duplizierung. Die Oberfläche ist vollständig über Dict-Optionen lokalisierbar: dictCancelUpload, dictRemoveFile, dictMaxFilesExceeded und etwa zwei Dutzend weitere Schlüssel. Die Unterstützung der deutschen Sprache ist in fünf Minuten eingerichtet, indem man ein Objekt aus der Dokumentation kopiert. Die Bibliothek wiegt 28 KB komprimiert (gzip) und verlängert die Seitenladezeit im mobilen 4G-Netz um weniger als 0,1 Sekunden. All diese Eigenschaften machen Dropzone.js zum De-facto-Standard für Drag-and-Drop-Uploads in Projekten ohne Frameworks: eine Million npm-Downloads pro Woche Anfang 2026 und Einsatz in WordPress-, Laravel- und Symfony-Admin-Panels.

Redaktion
RedaktionRedaktionsteam→ All publications

Ein professionelles Team von Autoren und Redakteuren, das auf die Erstellung hochwertiger Inhalte spezialisiert ist.