srhinow / download-bundle

2.3.1 2026-10-09 16:18 UTC

Requires

• php: >=8.3
• ext-json: *
• contao/core-bundle: ^5.3
• srhinow/contao-tags: ^5.0.6
• symfony/form: ^7.2

Requires (Dev)

• phpunit/phpunit: ^11.5

LGPL-3.0-or-later

• Sven Rhinow

• download
• contao

Published on Packagist.org on 2026-10-09 14:18 UTC

README

Contao-Bundle zur zentralen Verwaltung von Downloads mit hierarchischen Kategorien im Backend und vielfältiger Ausgabe im Frontend. Unterstützt Dateianhänge, Vorschaubilder, Tags (srhinow/contao-tags), Volltextsuche, Kategorie-Filter und einen konfigurierbaren Detailseitenlink.

Anforderungen

Abhängigkeit	Version
PHP	≥ 8.3
Contao Core Bundle	^5.3
srhinow/contao-tags	^5.0.6
symfony/form	^7.2
ext-json	*

Installation

composer require srhinow/download-bundle

Nach der Installation die Datenbank-Migration ausführen:

php bin/console contao:migrate

Backend

Das Bundle fügt unter Inhalte → Downloads (do=downloads) ein Backend-Modul hinzu. Über die globale Operation „Download-Kategorien" gelangt man zur Kategorieverwaltung.

Download-Kategorien (tl_download_categories)

Hierarchische Kategorieverwaltung (Baumstruktur via pid, bis zu 3 Ebenen tief, Sortierung per Drag & Drop).

Feld	Beschreibung
Name	Bezeichnung der Kategorie (Pflichtfeld, max. 255 Zeichen)
Alias	URL-freundlicher Bezeichner (automatisch generiert)
Sortierung (sorting)	Numerische Sortierreihenfolge

Downloads (tl_downloads)

Hauptverwaltung aller Download-Einträge.

Feld	Beschreibung
Name	Bezeichnung des Downloads (Pflichtfeld, max. 255 Zeichen)
Alias	URL-Alias (automatisch generiert, alphanumerisch + Underscore)
Kategorie	Zugeordnete Kategorien (Mehrfachauswahl, Pflichtfeld)
Datei	Datei aus der Contao-Dateiverwaltung (Pflichtfeld, Radio-Auswahl)
Bild hinzufügen (addImage)	Checkbox: Klappt das Feld „Vorschaubild" auf
Vorschaubild (singleSRC)	Optionales Vorschaubild (sichtbar im Backend-Listing als 100×100px-Thumbnail)
Tags	Tag-Auswahl via srhinow/contao-tags
Text	Beschreibungstext (TinyMCE-Editor)
Direkt-Link (direct_link)	Checkbox: Link führt direkt zur Datei statt zur Detailseite
Sortierung (sorting)	Manuelle numerische Sortierung
Seiten-Titel (pageTitle)	SEO-Seitentitel für die Detailansicht
Beschreibung (description)	SEO-Meta-Beschreibung
Online sichtbar (published)	Veröffentlichungs-Flag

Frontend-Module

Das Bundle registriert vier Frontend-Module in der Gruppe „Downloads":

download_list — Download-Liste

Zeigt veröffentlichte Downloads als gefilterte, durchsuchbare und paginierte Liste.

Feld	Beschreibung
Sprungseite (jumpTo)	Seite mit dem download_details-Modul für den Detailseitenlink
Dezimalstellen Dateigröße (download_size_decimal)	Anzahl der Nachkommastellen bei der Dateigrößenangabe (Standard: 1)
Download-Template	Item-Template für jeden Listeneintrag (alle Templates mit Präfix download_item_)

download_details — Download-Detailansicht

Zeigt alle Felder eines einzelnen Downloads. Liest den Download-Alias aus der URL.

Feld	Beschreibung
Download-Template	Item-Template für die Detailausgabe

download_search — Download-Suche

Ergebnisanzeige für das Filterformular — hat kein eigenes Formular. Liest category, tag und search aus der URL bzw. dem POST des download_filter-Moduls und zeigt die Treffer nach Kategorien gruppiert. Ohne Parameter erscheint nur ein Hinweistext.

Zum Unterschied zu download_list siehe Liste oder Suche?.

Feld	Beschreibung
Download-Template	Item-Template für die Suchergebnis-Ausgabe

download_filter — Download-Filter

Filterformular für die Download-Liste mit drei Feldern:

• Kategorie — die Kategorien, die die Liste auf dieser Seite als Abschnitte zeigt (Seiteneinstellung „Download-Kategorien“, sonst alle)
• Tag — nur sichtbar, wenn Downloads Tags haben (eingeschränkt über die Seiteneinstellung „Download-Tags“)
• Suche — Volltext in Name und Beschreibung

Ohne Sprungseite filtert das Modul die Download-Listen auf derselben Seite per AJAX – sowohl das Modul als auch das Inhaltselement „Download-Liste“; jQuery wird dafür nicht benötigt. Mit Sprungseite wird das Formular dorthin abgeschickt. Die Liste liest die Parameter category, tag und search auch direkt aus der URL.

Feld	Beschreibung
Sprungseite (jumpTo)	Seite mit der gefilterten Download-Liste

Liste oder Suche?

download_list und download_search zeigen beide gefilterte Downloads, sind aber für unterschiedliche Seiten gedacht:

	download_list	download_search
Ohne Filter	zeigt alle Downloads	zeigt nichts, nur einen Hinweistext
Welche Downloads	nur die Kategorien aus der Seiteneinstellung „Download-Kategorien“ (sonst alle)	alle veröffentlichten Downloads, unabhängig von der Seite
Gliederung	nach den Kategorien der Seite, mit dritter Ebene	nach den Kategorien jedes Treffers, als Pfad „Ober- / Unterkategorie“
Suche	Suchtext muss als Ganzes vorkommen	jedes Wort einzeln, ein Treffer genügt
Aktualisierung	per AJAX beim Ändern des Filters	beim Seitenaufruf (Formular abgeschickt oder Parameter in der URL)

Kurz: Die Liste ist eine durchstöberbare Übersicht, die sich eingrenzen lässt. Die Suche ist eine Trefferliste für eine eigene Ergebnisseite.

Typische Aufbauten:

• Eine Downloadseite mit Filter: download_filter ohne Sprungseite und download_list auf derselben Seite. Der Filter aktualisiert die Liste per AJAX. Ein zusätzliches download_search-Modul auf dieser Seite würde die Treffer doppelt zeigen.
• Eigene Ergebnisseite: download_filter mit Sprungseite (z. B. als Suchfeld im Seitenkopf) und auf der Zielseite download_search.

Insert-Tags

Insert-Tag	Beschreibung
{{download::search}}	Aktueller Suchwert aus dem POST-Request (Suchformular)
{{download::tag}}	Aktuell gesetzter Tag-Filter aus dem POST-Request

Suchindex

Der getSearchablePages-Hook (GetSearchablePagesListener) fügt alle veröffentlichten Downloads dem Contao-Suchindex hinzu, sofern ein download_details-Modul mit einer konfigurierten Sprungseite (jumpTo) vorhanden ist.

parseDownload-Hook

Nach dem Aufbereiten eines Download-Datensatzes feuert der parseDownload-Hook und erlaubt projektspezifische Nachbearbeitung:

$GLOBALS['TL_HOOKS']['parseDownload'][] = [MyClass::class, 'myMethod'];

Datenbankstruktur

tl_download_categories

Spalte	Typ	Beschreibung
id	int(10) unsigned PK AI	Primärschlüssel
pid	int(10) unsigned	Elternkategorie (0 = Root)
sorting	int(10) unsigned	Sortierung
tstamp	int(10) unsigned	Zeitstempel letzte Änderung
modify	int(10) unsigned	Reservierter Änderungstimestamp
name	varchar(255)	Kategoriename
alias	varchar(128)	URL-Alias

tl_downloads

Spalte	Typ	Beschreibung
id	int(10) unsigned PK AI	Primärschlüssel
tstamp	int(10) unsigned	Zeitstempel letzte Änderung
modify	int(10) unsigned	Reservierter Änderungstimestamp
sorting	int(10) unsigned	Sortierung
name	varchar(255)	Download-Bezeichnung
alias	varchar(128)	URL-Alias
category	blob NULL	Zugeordnete Kategorien (serialisiert)
file	binary(16) NULL	Datei-UUID aus tl_files
dl_url	varchar(255)	Optionale externe Datei-URL
tags	char(1)	Tag-Zuordnung (via contao-tags)
text	text NULL	Beschreibungstext (HTML)
direct_link	char(1)	Direkt-Link zur Datei
addImage	char(1)	Vorschaubild aktiv
singleSRC	binary(16) NULL	Vorschaubild-UUID aus tl_files
published	boolean	Veröffentlicht
pageTitle	varchar(255)	SEO-Seitentitel
description	text NULL	SEO-Meta-Beschreibung

Templates anpassen

Eigene Item-Templates müssen mit dem Präfix download_item_ beginnen, damit sie im Backend-Dropdown erscheinen. Beispiel: download_item_card.html.twig.

Tests ausführen

vendor/bin/phpunit -c vendor/srhinow/download-bundle/phpunit.xml.dist

Changelog

Siehe CHANGELOG.md für die vollständige Versionshistorie.

Lizenz

LGPL-3.0-or-later

Autor

Sven Rhinow — sr-tag.de
Support: [e-mail]
Quellcode: gitlab.com/srhinow/download-bundle