Search by

dud / contao-pdf-preview

drum-und-dran

PDF-Dateien als responsive Bilder in News, Events und allen Inhaltselementen mit Bildauswahl – mit Seitenauswahl, wichtigem Bereich, Sicherheitsprüfung und Virenscan.

Package info

github.com/drum-und-dran/contao-pdf-preview

Homepage

Type:contao-bundle

pkg:composer/dud/contao-pdf-preview

Fund package maintenance!

drum-und-dran

Statistics

Installs: 2

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

1.0.4 2026-11-16 13:01 UTC

This package is auto-updated.

Last update: 2026-11-16 13:07:18 UTC


README

PDF-Dateien als responsive Bilder – in News, Events und überall, wo Contao ein Bild auswählen lässt.

Eine Open-Source-Erweiterung von Gunnar Haeuschkel / Drum und Dran für Contao 5.3 LTS, 5.7 LTS und 6.x.

Redakteure wählen im Backend einfach eine PDF statt eines Bildes aus, zum Beispiel einen Flyer, ein Programmheft oder eine Speisekarte. Im Frontend erscheint die gewünschte Seite als gestochen scharfe, responsive Grafik. Die PDF selbst bleibt dabei unverändert.

Für Redakteure: Eine Schritt-für-Schritt-Anleitung in einfacher Sprache liegt hier: docs/ANLEITUNG-REDAKTEURE.md.

English: README.en.md · Editor guide

Funktionen

PDF überall dort, wo ein Bild gewählt werden kann

  • News und Events (Beitragsbild)
  • Inhaltselemente: Bild, Text mit Bild, Hyperlink mit Bild, Akkordeon, YouTube/Vimeo-Vorschaubild, Galerie (auch PDFs aus ausgewählten Ordnern)
  • FAQ, Frontend-Module, Seiten und Erweiterungen von Drittanbietern: Jedes Dateiauswahlfeld, das Contaos Bild-Endungen verwendet, wird automatisch erkannt.
  • Insert-Tags {{image::…}} / {{figure::…}} und die Twig-Funktion figure()

Volle Contao-Bildpipeline

Die Ausgabe läuft über die Bildverarbeitung von Contao. Deshalb funktioniert alles, was Contao bei Bildern kann:

  • Responsive Bildgrößen (unter „Themes“, „Bildgrößen“) mit srcset, sizes, Pixeldichten und Media-Queries
  • moderne Formate (WebP/AVIF), Lazy Loading, Deferred Resizing
  • Großansicht/Lightbox
  • Metadaten der PDF aus der Dateiverwaltung (Alt-Text, Bildunterschrift, Link …)

Seitenauswahl, auch für mehrseitige PDFs

In der Dateiverwaltung wird pro PDF festgelegt, welche Seite(n) verwendet werden: 1, 3, 2,4, 1,3-5 oder * (alle).

  • Felder mit einem Bild (News, Events, Bild-Element …) zeigen die erste ausgewählte Seite.
  • Das neue Inhaltselement „PDF-Seiten“ zeigt mehrere Seiten als responsive Bilder: mit Bildgröße, Spaltenanzahl und Lightbox. Optional verlinkt jede Seite direkt auf die passende Stelle der PDF (#page=N). Die Seitenauswahl lässt sich pro Element überschreiben.

Bildausschnitt – wie bei Bildern im Contao-Standard

Der wichtige Bereich einer PDF-Seite wird in der Dateiverwaltung genauso festgelegt wie bei Bildern: mit Contaos eigenem Editor. Gespeichert wird er in den Standardfeldern importantPartX/Y/Width/Height.

  • Standard-Verhalten: Contao berücksichtigt den Bereich beim Zuschneiden auf feste Bildgrößen (Modus „crop“), genau wie bei Fotos.
  • „PDF nur im wichtigen Bereich anzeigen“: Mit diesem Haken wird die Seite fest auf den Bereich zugeschnitten, zum Beispiel um nur das Foto eines Flyers zu zeigen.

Die Originaldatei wird dabei nicht verändert (nicht-destruktiv).

Eigenes Vorschaubild (optional)

Pro PDF lässt sich ein eigenes Bild hinterlegen. Es ersetzt die gerenderte Hauptseite und dient als letzte Rückfallebene.

Funktioniert auf (fast) jedem Webhosting

Webhostings unterscheiden sich stark: Manche haben Imagick, andere nicht. Manchmal blockiert ImageMagick PDFs per Policy, oder exec() ist deaktiviert. Die Erweiterung nutzt deshalb eine Renderer-Kette und wechselt automatisch zur nächsten Stufe:

Stufe Renderer Voraussetzung
1 Imagick/Gmagick (Contao-Core) PHP-Extension + Ghostscript, PDF in der ImageMagick-Policy erlaubt
2 pdftoppm (Poppler) oder Ghostscript per Kommandozeile proc_open erlaubt, Programm installiert
3 Im Browser des Redakteurs mit pdf.js nichts, funktioniert auf jedem Hosting
4 Eigenes Vorschaubild in der Dateiverwaltung hinterlegt

Kann der Server nicht rendern, erzeugt das Backend beim Öffnen der PDF in der Dateiverwaltung die Seitenbilder automatisch im Browser (pdf.js ist mitgeliefert, es werden keine externen CDNs geladen). Der Server prüft die Bilder und speichert sie, danach werden sie wie gewohnt weiterverarbeitet. Die Dateiverwaltung zeigt jederzeit, welche Stufe gerade aktiv ist.

Gerenderte Seiten werden in assets/previews zwischengespeichert. Wird die PDF ersetzt, werden die Vorschauen automatisch neu erzeugt.

Sicherheit

PDFs sind ein beliebter Angriffsvektor. Die Erweiterung prüft deshalb jede PDF, bevor sie überhaupt einen Renderer erreicht. Diese Prüfung schützt auch Funktionen von Contao selbst, die PDFs rendern (Vorschaubilder im Download-Element, Dateivorschau im Backend).

Mehrstufige Prüfung (Grundsatz: im Zweifel blockieren):

  1. Größenlimit (Standard: 50 MB)
  2. Strenge Strukturprüfung: PDF-Header am Dateianfang, Dateiende-Marker vorhanden. Polyglot-Dateien und manipulierte Dateien werden abgewiesen.
  3. Verschlüsselte PDFs werden blockiert, weil ihr Inhalt nicht prüfbar ist.
  4. Aktive Inhalte werden erkannt und blockiert: JavaScript, Launch-Aktionen, eingebettete Dateien, XFA-Formulare, RichMedia/Flash, SubmitForm, ImportData, GoToE. Das gilt auch für maskierte Namen (/J#61vaScript) und für Inhalte in komprimierten Objekt-Streams. Nicht prüfbare Streams und Kompressionsbomben führen ebenfalls zur Sperre.
  5. Virenscan mit ClamAV, wahlweise über den clamd-Socket, clamdscan oder clamscan. Optional als Pflicht konfigurierbar.

Weitere Schutzmaßnahmen:

  • Ghostscript läuft immer mit -dSAFER, alle externen Prozesse mit Zeitlimit und ohne Shell (keine Kommando-Injection).
  • pdf.js läuft im Backend ohne eval, ohne XFA und ohne PDF-JavaScript.
  • Im Browser gerenderte Bilder werden auf Typ, Größe und Abmessungen geprüft und vollständig neu codiert. Angehängte Fremddaten werden dabei verworfen.
  • Der interne Endpunkt erfordert einen Backend-Login, Zugriff auf die Dateiverwaltung, Bearbeitungsrechte, die passende Dateifreigabe (Filemount) und ein gültiges Request-Token.
  • Unsichere PDFs lassen sich im Backend nicht als Bild auswählen. Beim Upload über die Contao-Dateiverwaltung wird sofort geprüft und gewarnt. Blockierte PDFs erscheinen im Frontend nicht.
  • Upload per FTP/SFTP oder Deployment: Die Prüfung hängt nicht am Upload-Weg. Jede PDF wird vor jeder Verarbeitung geprüft, egal wie sie auf den Server kam. Zusätzlich durchsucht ein stündlicher Contao-Cronjob das Dateiverzeichnis. Administratoren sehen blockierte Dateien als Hinweis auf der Backend-Startseite und im System-Log.
  • Prüfergebnisse werden anhand des Datei-Inhalts (Hash) zwischengespeichert. Eine per FTP ausgetauschte Datei wird auch dann neu geprüft, wenn Name, Datum und Größe gleich bleiben.
  • Mit contao-pdf-preview:scan lässt sich jederzeit manuell oder per System-Cron neu prüfen, z. B. nach Signatur-Updates von ClamAV.

Hinweis: Keine Software kann eine absolute Sicherheit garantieren. Die Prüfung senkt das Risiko deutlich. Ghostscript, Poppler, ImageMagick und ClamAV sollten immer aktuell sein. Für maximale Sicherheit wird ClamAV mit require_virus_scan: true empfohlen.

Vorschaubilder liegen wie alle Contao-Bilder öffentlich in assets/. PDFs aus geschützten Ordnern deshalb nur dann als Bild verwenden, wenn die gezeigte Seite öffentlich sein darf.

Installation

Über den Contao Manager: Nach „dud/contao-pdf-preview“ suchen, installieren und anschließend die Datenbank aktualisieren.

Über Composer:

composer require dud/contao-pdf-preview
vendor/bin/contao-console contao:migrate

Testversion als ZIP (ohne Packagist/GitHub): Im Contao Manager unter Pakete über „Pakete hochladen“ die Datei dud-contao-pdf-preview-<version>.zip hochladen, installieren und die Datenbank aktualisieren.

Systemvoraussetzungen

Contao PHP
5.3 LTS ab 8.1
5.7 LTS ab 8.3
6.x ab 8.4

Die Erweiterung selbst benötigt PHP 8.1 oder höher. Das tatsächliche Minimum gibt die jeweilige Contao-Version vor, Composer bzw. der Contao Manager wählen die passende Kombination automatisch.

Empfohlene Server-Ausstattung

  • ext-imagick mit Ghostscript oder poppler-utils (pdftoppm)
  • ClamAV (clamd)

Ohne diese Komponenten funktioniert die Erweiterung trotzdem. Dann wird im Browser gerendert, und es gibt keinen Virenscan. Die im Browser gerenderten Seitenbilder werden automatisch an das Upload-Limit des Servers (upload_max_filesize, post_max_size) angepasst. Ein Limit von mindestens 8 MB ergibt die beste Bildqualität.

Server-Rendering aktivieren

Zeigt die Dateiverwaltung „Vorschau: Browser (pdf.js)“, kann der Server PDFs nicht selbst rendern. Am einfachsten lässt sich das mit Poppler beheben (Debian/Ubuntu):

sudo apt install poppler-utils

Die Erweiterung findet pdftoppm automatisch, eine Konfiguration ist nicht nötig. Voraussetzung ist, dass PHP externe Programme starten darf (proc_open). Das ist der Fall, wenn ClamAV über clamdscan bereits funktioniert.

Alternativ über Imagick: php-imagick und ghostscript installieren und in der ImageMagick-Richtlinie (z. B. /etc/ImageMagick-6/policy.xml) das Lesen von PDF erlauben (<policy domain="coder" rights="read" pattern="PDF" />). Danach PHP-FPM neu starten.

Wird ein Renderer nachträglich installiert, rendert der Server die PDFs beim nächsten Aufruf automatisch selbst. Nur nach einer Änderung der ImageMagick-Richtlinie einmal vendor/bin/contao-console contao-pdf-preview:scan --purge-previews ausführen.

Berechtigungen für Redakteure

Administratoren haben automatisch alle Rechte. Für Redakteure werden in der Benutzergruppe (oder beim Benutzer) folgende Rechte vergeben. Alle Felder der Erweiterung beginnen mit „PDF“ und sind dadurch in der Liste eindeutig zu finden.

Bereich in der Gruppe Recht Wofür
Backend-Module Dateien Dateiverwaltung öffnen
Filemounts die gewünschten Ordner Zugriff auf die PDFs
Erlaubte Datei-Operationen Dateien und Verzeichnisse bearbeiten, kopieren und verschieben PDF-Einstellungen bearbeiten, Vorschau im Browser erzeugen
Erlaubte Felder, Dateien (tl_files) PDF-Seite(n) als Bild [pdfPreviewPages] Seitenauswahl
PDF: eigenes Vorschaubild [pdfPreviewImage] eigenes Vorschaubild
PDF nur im wichtigen Bereich anzeigen [pdfCropToImportantPart] fester Zuschnitt
x-/y-Koordinate, Breite und Höhe des wichtigen Teils [importantPart…] wichtiger Bereich (Contao-Standardfelder, wie bei Bildern)
Inhaltselemente Media-Elemente: PDF-Seiten Element „PDF-Seiten“
Erlaubte Felder, Inhaltselemente (tl_content) PDF-Seiten: Seitenauswahl [pdfPages], PDF-Seiten: mit PDF verlinken [pdfLinkToFile] Optionen des Elements

Die Vorschau samt Sicherheitsstatus ist kein eigenes Recht. Den Editor für den wichtigen Bereich zeigt sie nur, wenn die vier importantPart-Felder erlaubt sind. Der Hinweis auf blockierte PDFs auf der Backend-Startseite erscheint nur für Administratoren.

Konfiguration (optional)

In config/config.yaml (alle Werte sind Standardwerte):

contao_pdf_preview:
    preview_size: 2048          # Auflösung der gerenderten Seite (kürzere Kante, px)
    default_page: 1
    backend_fields: true        # PDFs in Bild-Auswahlfeldern erlauben
    excluded_fields: ['tl_theme.screenshot']   # z. B. 'tl_news.*'
    gallery: true               # PDFs in Galerien berücksichtigen
    lightbox: true              # Großansicht für PDF-Bilder
    cli_binary: ~               # Pfad zu pdftoppm/gs; ~ = automatisch, false = aus
    security:
        enabled: true
        max_file_size: 52428800
        max_decompressed_size: 104857600
        blocked_features: [JavaScript, JS, Launch, EmbeddedFile, EmbeddedFiles, RichMedia, XFA, SubmitForm, ImportData, GoToE]
        allow_encrypted: false
        virus_scan: auto        # auto | clamav | off
        require_virus_scan: false
        clamav_socket: ~        # z. B. /run/clamd.scan/clamd.sock oder tcp://127.0.0.1:3310
        clamav_binary: ~

Konsolenbefehl

vendor/bin/contao-console contao-pdf-preview:scan               # alle PDFs in files/ prüfen
vendor/bin/contao-console contao-pdf-preview:scan files/flyer   # bestimmter Ordner/Datei
vendor/bin/contao-console contao-pdf-preview:scan --no-cache --purge-previews

Für Entwickler

Technisch dekoriert die Erweiterung den Service contao.image.factory. Wird ein PDF-Pfad übergeben, wird er transparent durch die geprüfte, gerenderte und ggf. zugeschnittene Seite ersetzt. Dadurch funktionieren alle Stellen, die Contaos Bildpipeline nutzen, ohne Template-Änderungen. Das Rendern übernimmt Contaos PreviewFactory, ergänzt um eigene Preview-Provider (Sicherheitsschranke, CLI-Fallback). Der wichtige Bereich aus tl_files.importantPart* wird als ImportantPart an das gerenderte Seitenbild übergeben.

Templates: content_element/pdf_pages.html.twig kann wie jedes Contao-Template angepasst werden.

Sponsoring

Die Erweiterung ist kostenlos und quelloffen. Weiterentwicklung, Pflege und die Kompatibilität mit neuen Contao-Versionen kosten jedoch Zeit. Unterstützung ist über GitHub Sponsors möglich:

github.com/sponsors/drum-und-dran

Auch Firmen können gezielt Funktionen sponsern. Kontakt: drum-und-dran.de

Lizenz & Kontakt

MIT-Lizenz. Mitgeliefert: pdf.js (Apache License 2.0).

Gunnar Haeuschkel / Drum und Dran · drum-und-dran.de · Fehler und Wünsche: GitHub Issues · Sponsor werden