Skip to main content

⚙️ MODX cleanUpload

Info

Diese Seite dokumentiert das Plugin-Snippet cleanUpload für MODX Revolution.
Es erweitert den Dateimanager (Media Browser) um automatische Bereinigung und Optimierung hochgeladener Dateien.
Entwickelt zur Verbesserung der Dateiverwaltung, Einhaltung von DSGVO-Vorgaben und zur Vermeidung fehlerhafter oder doppelt benannter Dateien.

cleanUpload — Überblick

Das Plugin cleanUpload wird beim Hochladen von Dateien im MODX File Manager ausgeführt.
Es prüft, bereinigt, optimiert und sichert Dateien automatisch während des Upload-Vorgangs ab.

💡 Hinweis

Das Plugin reagiert auf die System-Events
OnFileManagerBeforeUpload und OnFileManagerUpload.

Features

  • Bereinigt und normalisiert Dateinamen (Transliteration, Klein-/Großschreibung)
  • Verhindert das Überschreiben vorhandener Dateien (automatische Umbenennung mit _1, _2, … oder eindeutiger ID)
  • Skalierung und Optimierung von Bildern (JPEG, PNG, GIF) mit Transparenz-Erhalt
  • Überspringt animierte GIFs automatisch
  • Entfernt Metadaten aus Bildern und PDF-Dateien (Ghostscript über pdf2ps / ps2pdf)
  • Konfigurierbare Schalter für Bild- und PDF-Optimierung sowie Admin-Bypass
  • Kompatibel mit MODX 2.8.x und MODX 3.x
  • DSGVO-konforme Verarbeitung (keine Metadaten, keine Tracking-Infos)

Voraussetzungen

Komponente Erforderlich
PHP ≥ 8.2
GD / GD2 zum Verarbeiten und Verkleinern von Bildern
Ghostscript zur PDF-Neuschreibung und Metadatenentfernung
MODX-Einstellungen Systemevents aktivieren: OnFileManagerBeforeUpload, OnFileManagerUpload

MODX 3 – Hinweis zur Transliteration

Ab MODX 3 muss die automatische Transliteration in den Systemeinstellungen deaktiviert werden,
da cleanUpload eine eigene Dateinamen-Normalisierung nutzt.

⚙️ Einstellung

  • Schlüssel: upload_translit
  • Typ: Ja/Nein
  • Standard: Ja
  • Für cleanUpload: Nein

Arbeitsweise

  1. Dateinamen prüfen und bereinigen

    • Sonderzeichen, Leerzeichen und problematische Zeichen werden durch _ ersetzt.
    • Umlaute bleiben erhalten (keine erzwungene ASCII-Transliteration).
    • Groß-/Kleinschreibung der Dateierweiterung wird vereinheitlicht.

  2. Dateikonflikte vermeiden

    • Bereits vorhandene Dateien werden nicht überschrieben.
    • Vor dem Upload wird eine bestehende Datei automatisch auf _1, _2, … umbenannt.
    • Falls dennoch ein Konflikt entsteht (z. B. bei gleichzeitigen Uploads oder unerwarteten Systemzuständen),
      erhält der neue Upload eine eindeutige ID wie _63f9c6a8b2a1e.
    • So ist sichergestellt, dass keine Datei überschrieben wird, selbst bei Mehrfach-Uploads oder Race Conditions.

  3. Bildoptimierung (konfigurierbar)

    • Maximale Standardgröße: 1280 × 1280 px
    • JPEG-Qualität: 80 %
    • Transparenz bei PNG/GIF bleibt vollständig erhalten.
    • Animierte GIFs werden erkannt und übersprungen.
    • Aktivierung/Deaktivierung über den Schalter $enableImageOptimize.
    • Anpassbare Parameter im Plugin-Code:
      • $maxWidth, $maxHeight, $quality

  4. PDF-Optimierung (konfigurierbar)

    • PDFs werden mit pdf2ps → ps2pdf neu geschrieben.
    • Entfernt Metadaten, Versionseinträge und unnötige Strukturen.
    • Aktivierung/Deaktivierung über den Schalter $enablePdfOptimize.
    • Wiederholungsversuche und Wartezeit über Konstanten definierbar:
      • PDF_PROCESSING_ATTEMPTS (Standard = 3)
      • PDF_PROCESSING_WAIT (Standard = 5 Sekunden)

  5. Admin-Bypass (optional)

    • Wenn $adminBypass = true, werden im Manager-Kontext (mgr)
      keine Normierungen oder Optimierungen ausgeführt.

Fehlermeldungen & Log-Einträge

Fehlerquelle Logmeldung Log-Level
GD-Erweiterung fehlt [cleanUpload] Error: GD extension not loaded ERROR
Fehler beim Upload [cleanUpload] Error during upload: … ERROR
Ungültiger oder leerer Dateiname [cleanUpload] Filename normalization failed. ERROR
Bild konnte nicht verkleinert werden [cleanUpload] Image resize failed for … ERROR
PDF nicht gefunden (nach Wartezeit) [cleanUpload] PDF not found after attempts. ERROR
PDF-Tools fehlen (pdf2ps / ps2pdf) [cleanUpload] pdf2ps/ps2pdf not available on server. ERROR
Fehler bei der PDF-Verarbeitung [cleanUpload] PDF processing failed. ERROR
Animiertes GIF erkannt – Überspringen [cleanUpload] Skip animated GIF: … INFO (sichtbar nur bei log_level = INFO oder niedriger)

Sicherheit & Datenschutz

  • Entfernt EXIF- und IPTC-Daten aus Bildern
  • Entfernt PDF-Metadaten automatisch
  • Keine personenbezogenen Daten im Dateisystem
  • DSGVO-konform, auch bei öffentlichen Uploads

Testumgebung

Getestet mit:

  • MODX 2.8.8 (PHP 8.2.27)
  • MODX 3.1.0 (PHP 8.3.14)
  • MODX 3.1.2 / 3.1.4 (PHP 8.4.12)

🔧 Empfehlung

Vor Produktiveinsatz sollte cleanUpload in einer Testumgebung geprüft werden
(z.B. Schreibrechte, verfügbare Tools, Serverpfade, Dateigrößenlimits).

Fazit

Das Plugin cleanUpload bietet eine stabile, DSGVO-konforme Lösung für Uploads im MODX-Filemanager.
Es arbeitet unabhängig von der MODX-eigenen Transliteration, prüft und optimiert Dateien vollautomatisch
und ist besonders geeignet für Projekte mit häufigen Bild- oder PDF-Uploads.
Die zweistufige Kollisionserkennung stellt sicher, dass keine Datei überschrieben wird –
egal ob beim Einzel- oder Mehrbenutzer-Upload.

Back to top