dud / contao-pdf-preview
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
Type:contao-bundle
pkg:composer/dud/contao-pdf-preview
Fund package maintenance!
Requires
- php: ^8.1
- contao/core-bundle: ^5.3 || ^6.0
- contao/image: ^1.2
- doctrine/dbal: ^3.6 || ^4.0
- imagine/imagine: ^1.3
- psr/cache: ^1.0 || ^2.0 || ^3.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- symfony/config: ^6.4 || ^7.4 || ^8.0
- symfony/console: ^6.4 || ^7.4 || ^8.0
- symfony/dependency-injection: ^6.4 || ^7.4 || ^8.0
- symfony/filesystem: ^6.4 || ^7.4 || ^8.0
- symfony/finder: ^6.4 || ^7.4 || ^8.0
- symfony/http-foundation: ^6.4 || ^7.4 || ^8.0
- symfony/http-kernel: ^6.4 || ^7.4 || ^8.0
- symfony/process: ^6.4 || ^7.4 || ^8.0
- symfony/routing: ^6.4 || ^7.4 || ^8.0
- symfony/security-bundle: ^6.4 || ^7.4 || ^8.0
- symfony/security-csrf: ^6.4 || ^7.4 || ^8.0
Requires (Dev)
- contao/manager-plugin: ^2.3
- phpunit/phpunit: ^10.5 || ^11.0
Suggests
None
Provides
None
Conflicts
- contao/manager-plugin: <2.0 || >=3.0
Replaces
None
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-Funktionfigure()
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):
- Größenlimit (Standard: 50 MB)
- Strenge Strukturprüfung: PDF-Header am Dateianfang, Dateiende-Marker vorhanden. Polyglot-Dateien und manipulierte Dateien werden abgewiesen.
- Verschlüsselte PDFs werden blockiert, weil ihr Inhalt nicht prüfbar ist.
- 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. - Virenscan mit ClamAV, wahlweise über den clamd-Socket,
clamdscanoderclamscan. 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:scanlä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: trueempfohlen.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-imagickmit Ghostscript oderpoppler-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