README

🇬🇧 English version

File Inspector ist ein Contao-Backend-Modul, das Dateien im Upload-Verzeichnis (/files) findet, die nirgendwo mehr referenziert werden, für jede Datei genau zeigt, warum sie als verwendet oder unverwendet gilt, und das sichere Aufräumen — mit Sicherungskopie und Papierkorb — direkt aus dem Backend heraus ermöglicht. Zusätzlich bietet es Werkzeuge zum Minifizieren von CSS/JS und zur Bildformat-Optimierung.

1. Projektübersicht

File Inspector durchsucht die Contao-Datenbank (und optional den Projekt-Quellcode) nach Referenzen auf Dateien im Upload-Verzeichnis und stuft jede Datei als Referenziert, Unsicher oder Keine Referenz gefunden ein. Auf dieser Grundlage lassen sich unbenutzte Dateien geprüft, exportiert und sicher gelöscht werden — mit einem integrierten Papierkorb für den Fall, dass eine Einschätzung doch nicht zutraf.

2. Aktueller Implementierungsstatus

File Inspector ist eine vollständige, aktuelle native Implementierung — kein Prototyp, kein Platzhalter und kein reiner Nur-Lese-Zustand. Alle in diesem Dokument beschriebenen Funktionen sind end-to-end mit einer serverseitigen Umsetzung verbunden und wurden gegen den tatsächlichen Quellcode geprüft.

3. Unterstützte Framework- und Laufzeitversionen

Contao 5.3 oder neuer
PHP 8.2 oder neuer
Symfony 6.4 oder 7.0
Doctrine DBAL 3.6 oder 4.0

4. Systemvoraussetzungen

PHP-Erweiterung sodium (Prüfung signierter Lizenzdaten)
PHP-Erweiterung curl (gesicherte Kommunikation mit dem Lizenzdienst)
PHP-Erweiterung pdo (Datenbankzugriff)
PHP-Erweiterung zip (nur für die Funktion Export & Löschen erforderlich)
PHP-Erweiterung gd (für Bildoptimierung; von Contao ohnehin vorausgesetzt)
PHP-Erweiterung imagick (optional; nur nötig, um SVG-Dateien als Quelle für die Bildoptimierung zu nutzen)

5. Installation

composer require vtinnovations/file-inspector

Anschließend die Contao-Datenbankmigration ausführen, um die benötigten Tabellen anzulegen:

php bin/console contao:migrate

Das Bundle registriert sich über sein Contao-Manager-Plugin automatisch.

6. Composer-/Framework-Einrichtung

Das Paket ist als contao-bundle deklariert und wird vom Contao Manager automatisch erkannt und geladen — es ist keine manuelle Bundle-Registrierung nötig.

7. Erforderliche ausführbare Programme und Konfiguration

Außer der Contao-Datenbankmigration (Schritt 5) ist keine zusätzliche Konfiguration erforderlich. Ignorierregeln, Aufbewahrungsrichtlinien und die Lizenz werden über die Backend-Oberfläche verwaltet, nicht über Konfigurationsdateien.

8. Dateisystemberechtigungen

Der PHP-Prozess benötigt Schreibzugriff auf folgende Verzeichnisse unterhalb von var/ (werden bei Bedarf automatisch angelegt):

var/fi_scans/, var/fi_scan_jobs/, var/fi_exports/, var/fi_bin/
var/fi_settings.json, var/fi_retention.json, var/fi_minified.json
var/log/file_inspector/
var/file_inspector/ (Lizenzdaten, siehe Lizenzierung)

9. Backend- und Administrationszugriff

Das Modul erscheint im Contao-Backend unter System › File Inspector. Der Zugriff wird über die reguläre Contao-Backend-Benutzergruppenverwaltung gesteuert — das Modul muss der jeweiligen Benutzergruppe wie jedes andere Backend-Modul zugewiesen werden. Die Lizenzverwaltung selbst befindet sich unter Contao › Einstellungen › File Inspector Licence management.

10. Frontend-Integration

Nicht zutreffend — File Inspector ist ausschließlich ein Backend-Werkzeug und stellt keine Frontend-Module oder -Inhaltselemente bereit.

11. Navigationsmodule in der tatsächlichen Reihenfolge

Reihenfolge	Bezeichnung im Backend	Zweck
1	🔍 File Inspector	Übersicht, Scan starten, Ergebnisse
2	🔎 Verwendung	File Usage Explorer
3	🗜 Minifizieren	CSS/JS minifizieren
4	🖼 Bilder optimieren	Bildformat-Konvertierung
5	🕐 Verlauf	Scan-Verlauf
6	🗑 Papierkorb	Gelöschte Dateien verwalten
7	⚙ Ignorierregeln	Ausschluss von Ordnern/Endungen
8	🔑 Lizenz	Verweis auf Contao › Einstellungen

12. Verifizierte Funktionen aller wesentlichen Module

Normal Scan

Ein schneller, rein datenbankbasierter Scan. Er sammelt jede referenzierte Datei-UUID über:

DCA-Dateifelder — jede tl_*-Spalte mit inputType: fileTree oder eval.files / eval.filesOnly.
HTML-/Textinhalte — Einfügemarken ({{file::…}}, {{image::…}}, …), HTML-Attribute (src/href/data-*), CSS-url()-Aufrufe und bare Upload-Pfade in jedem textarea-, codeEditor- oder Rich-Text-Feld.

Beide Quellen werden zeilenweise per Doctrine DBAL gestreamt, sodass der Speicherverbrauch auch bei großen Installationen konstant bleibt. Auf jeder Lizenzstufe verfügbar, einschließlich der kostenlosen.

Deep Scan

Alles aus dem Normal Scan plus einem Durchsuchen der Projekt-Quelldateien (PHP, Twig, HTML, JS, TS, CSS, SCSS, Less, JSON, YAML, XML, SVG, …) unter src/, templates/, config/, vendor/ und public/. Deep Scan ergänzt:

Quelldatei-Referenzen — fest im Code, in Templates oder Konfiguration hinterlegte Dateipfade und UUIDs.
CSS-Abhängigkeitsauflösung — transitive @import- / @use- / @forward- / url()-Ketten, sodass eine CSS-/SCSS-Teildatei, die nur von einer anderen Stylesheet eingebunden wird, weiterhin korrekt als verwendet gilt.
Unsicherheitserkennung — siehe unten.

Deep Scan ist langsamer und benötigt mehr Speicher. Nur auf der Pro-Stufe verfügbar.

Unsicherheitserkennung

Manche Dateien lassen sich weder als verwendet noch als unverwendet beweisen — etwa ein zur Laufzeit zusammengesetzter Dateiname oder ein Name, den mehrere Dateien teilen. Anstatt zu raten, markiert Deep Scan solche Dateien als Unsicher und dokumentiert den Grund: Fundstelle, ein kurzer Codeausschnitt und eine verständliche Erklärung — ein Dateiname als eigenständiges Literal, ein Teilpfad ohne Upload-Präfix, ein Dateiname neben einer Verkettung/Interpolation, oder ein Dateiname, der von mehreren Dateien geteilt wird (mehrdeutiger Treffer).

File Usage Explorer

Zeigt für jede Datei, wo genau sie verwendet wird — vollständig aus einem gespeicherten Scan aufgebaut, ohne erneut zu scannen:

Datenbankreferenzen mit sprechendem Tabellennamen, dem Titel des Datensatzes (soweit auflösbar), einer Hierarchie übergeordneter Datensätze (z. B. Seite → Artikel → Inhaltselement) und einem Bearbeiten-Link, der den Datensatz in einem neuen Backend-Tab öffnet.
Template-Referenzen (Twig / .html5), nach Pfad angezeigt.
Weitere Quelldatei-Referenzen, nach Sprache gruppiert (PHP, JavaScript, CSS, …).

Evidence Viewer

Jede Referenz basiert auf einem Beleg. Der Evidence Viewer stellt jeden Beleg als verständliches Typ-/Fundort-/Beschreibung-Tripel dar (Datenbank, Template, CSS, PHP, Twig, …) statt roher interner Kennungen.

Export & Löschen

Bereinigt unreferenzierte Dateien sicher, in drei getrennten Anfragen, sodass ein ZIP-Download und eine Löschung niemals gekoppelt sind:

Dateien auswählen und einen ZIP-Export erstellen; eine Bestätigungsseite zeigt Anzahl, Gesamtgröße und hebt ausgewählte Unsichere Dateien hervor.
Das Archiv herunterladen.
Ausdrücklich Jetzt löschen bestätigen — oder abbrechen, wodurch der ausstehende Export verworfen wird, ohne etwas zu löschen.

Löschungen verschieben die Datei in den Papierkorb und entfernen ihren Eintrag aus der Contao-Dateiverwaltung. Jede Löschung wird im Prüfprotokoll unter var/log/file_inspector/deletions.log festgehalten. Alle Pfade werden unmittelbar vor jeder Verschiebung erneut geprüft (Eingrenzung, Traversierung, symbolische Links); ein einzelner Stapel ist auf 500 Dateien begrenzt. Nur auf der Pro-Stufe verfügbar.

Papierkorb

Gelöschte Dateien werden nicht zerstört, sondern in einen Papierkorb verschoben und dort aufbewahrt, bis sie manuell geleert werden (kein automatischer Ablauf). Eine Wiederherstellung bringt die Datei an ihren ursprünglichen Ort zurück und stellt ihren Dateiverwaltungs-Eintrag mit der ursprünglichen UUID wieder her, sodass jedes Inhaltselement, jede Galerie oder jeder Download, der auf sie verwiesen hat, weiterhin funktioniert — als wäre sie nie gelöscht worden. Belegt bereits eine Datei den ursprünglichen Pfad, bietet die Wiederherstellung eine Auswahl zwischen Ersetzen und Überspringen (mit „Für alle anwenden“). Die Wiederherstellung steht immer zur Verfügung, auch ohne Pro-Lizenz.

Scan-Verlauf

Jeder abgeschlossene Scan wird automatisch gespeichert. Vergangene Scans lassen sich mit Modus, Datum, Dauer und Ergebniszusammenfassung durchsuchen; jeder Scan kann erneut geöffnet werden, ohne neu zu scannen. Alte Scans werden automatisch bereinigt: eine feste Obergrenze hält die letzten 50 Scans, eine von der Bedienperson konfigurierbare Alterrichtlinie (über die Verlaufsseite, Pro-Stufe) kann früher eingreifen. Der zuletzt gespeicherte Scan wird von keiner der beiden Richtlinien jemals entfernt.

Ignorierregeln

Schließt Ordner und Dateiendungen vom Scan aus — etwa files/archiv oder *.php. Exakte Namen und Glob-Muster (*, ?, […]) werden unterstützt; reguläre Ausdrücke nicht. Konfigurierbar unter Ignorierregeln (Pro-Stufe). Standardwerte: Ordner archive, backup, import, old, legacy; Endungen php, phar, phtml.

AJAX-Scan-Jobs

Scans laufen als inkrementelle Hintergrund-Jobs per AJAX, die die Arbeit in Stapeln (500 Upload-Dateien / 25 Quelldateien pro Anfrage) über mehrere Anfragen verteilen. Das hält jede Anfrage deutlich innerhalb üblicher PHP-Zeitlimits, zeigt einen Live-Fortschritt und blockiert das Backend nie durch eine einzelne lange Anfrage. Eine Sperrdatei verhindert zwei gleichzeitige Scans. Nur auf der Pro-Stufe verfügbar — auf der kostenlosen Stufe läuft ein Normal Scan weiterhin, jedoch synchron in einer einzigen blockierenden Anfrage ohne Fortschrittsanzeige.

Minifizieren (CSS/JS)

Listet jede CSS-/JS-Datei im Upload-Verzeichnis auf — unabhängig vom Verwendungsstatus — und minifiziert eine gewählte Auswahl direkt an ihrem Speicherort (keine neue .min.css-Datei). Nur Leerzeichen- und Kommentar-Minifizierung wird durchgeführt, keine Verhaltensänderungen. Vor jedem Überschreiben wird eine Sicherungskopie angelegt, sodass eine fehlerhafte Minifizierung rückgängig gemacht werden kann. Bereits minimale Dateien bleiben unangetastet und werden als übersprungen markiert. Nur auf der Pro-Stufe verfügbar.

Bildoptimierung

Wandelt Bilder (JPEG, PNG, GIF, WebP, BMP oder SVG als Quelle) in WebP, AVIF oder ICO um, ohne die Originaldatei zu verändern — die konvertierte Datei entsteht neu am selben Speicherort. WebP/AVIF stehen zur Verfügung, wenn die jeweilige Kodierfunktion in der GD-Erweiterung des Servers vorhanden ist; ICO ist immer verfügbar. SVG-Quellen erfordern zusätzlich die optionale Imagick-Erweiterung mit SVG-Unterstützung. Auf dem jeweiligen Server nicht unterstützte Kombinationen werden in der Oberfläche mit Begründung deaktiviert angezeigt. Nur auf der Pro-Stufe verfügbar.

13. Berechtigungen und Zugriffskontrolle

Der Zugriff auf das Modul wird durch die reguläre Contao-Backend-Benutzergruppenverwaltung gesteuert (Modulzuweisung wie bei jedem anderen Backend-Modul). Jede schreibende Aktion prüft zusätzlich ein gültiges Contao-Anfrage-Token. Innerhalb des Moduls entscheidet die aktive Lizenz zusätzlich darüber, welche Funktionen zur Verfügung stehen (siehe Abschnitt 14).

14. Lizenz- und Berechtigungsverhalten

File Inspector ist ein kommerziell lizenziertes Bundle. Auch die kostenlose Stufe erfordert eine aktivierte Lizenz. Die Lizenz wird ausschließlich unter Contao › Einstellungen › File Inspector Licence management verwaltet — es gibt keine Lizenzseite innerhalb des Moduls selbst.

Eine Lizenz ist an exakte Hostnamen gebunden, die aus der Domain-Einstellung der Root-Seiten stammen. example.com und www.example.com gelten als unterschiedliche Domains. Eine Installation ohne konfigurierte Domain kann keine Lizenz aktivieren.

Während des normalen Betriebs kontaktiert das Bundle bei bestimmten lizenzbezogenen Vorgängen den Lizenzdienst unter v-t.one über eine vertrauenswürdige HTTPS-Verbindung, um die Berechtigung zu prüfen. Anfragen gehen ausschließlich vom Server aus, niemals aus dem Browser; Lizenzschlüssel und weiteres Authentifizierungsmaterial erscheinen nicht in Browser-Ausgaben oder regulären Protokollen.

Vollständige Details — Aktivierung, tatsächliche Lizenzzustände und die Funktionsfreischaltungs-Tabelle — stehen in der eigenständigen Lizenzierung-Dokumentation.

15. Funktionsstatus-Tabelle

Funktion	Status
Normal Scan	Free und Pro
Deep Scan	Nur Pro
Unsicherheitserkennung (Teil von Deep Scan)	Nur Pro
File Usage Explorer / Evidence Viewer	Free und Pro
Export & Löschen	Nur Pro
Papierkorb / Wiederherstellung	Free und Pro
Scan-Verlauf ansehen	Free und Pro
Scan-Verlauf löschen / Aufbewahrungsrichtlinie	Nur Pro
Ignorierregeln	Nur Pro
AJAX-Hintergrund-Scans	Bedingt — auf der kostenlosen Stufe läuft ein Normal Scan stattdessen synchron ohne Fortschrittsanzeige
Minifizieren (CSS/JS)	Nur Pro
Bildoptimierung	Nur Pro
Frontend-Module	Nicht zutreffend

Die vollständige Aufschlüsselung nach Lizenzstufe steht in der Lizenzierung-Dokumentation.

16. Sicherheitsmodell

Jeder von der Oberfläche übermittelte Dateipfad wird vor jeder Dateisystemänderung geprüft (Eingrenzung auf das Upload-Verzeichnis, Ablehnung von Traversierung und symbolischen Links) — unmittelbar vor jeder einzelnen Operation erneut. Jede geschützte Funktion prüft ihre eigene Berechtigung serverseitig, unabhängig von der Oberfläche. Details stehen im eigenständigen Sicherheitsmodell.

17. Betriebssicherheit

Löschvorgänge sind nicht destruktiv (Papierkorb statt sofortigem Entfernen), ZIP-Export und Löschung sind in getrennte Anfragen aufgeteilt, und Minifizierung/Bildkonvertierung legen vor jeder Änderung eine Sicherungskopie an bzw. erzeugen ausschließlich neue Dateien, ohne die Quelle zu verändern. Schreibvorgänge auf Dateien erfolgen atomar (temporäre Datei plus Umbenennung).

18. Laufzeitverzeichnisse

Alle Laufzeitdaten liegen unterhalb von var/ (siehe Abschnitt 8 sowie Architektur für die vollständige Übersicht).

19. Externe Kommunikation

Die einzige externe Serverkommunikation erfolgt mit dem Lizenzdienst unter v-t.one, über vertrauenswürdige HTTPS-Verbindungen und ausschließlich vom Server aus — niemals aus dem Browser der Bedienperson. Details stehen in der Lizenzierung.

20. Protokollierung und Schwärzung vertraulicher Daten

Betriebsprotokolle (Löschungen unter var/log/file_inspector/deletions.log, Minifizierung und Bildoptimierung) enthalten Vorgang, Ergebnis, Zeitstempel und betroffene Pfade — keine Lizenzschlüssel oder sonstigen vertraulichen Daten.

21. Deployment

File Inspector wird wie jedes andere Contao-Bundle über Composer ausgeliefert. Nach einem Deployment ist contao:migrate auszuführen (siehe Abschnitt 5). Bei einem Mehr-Server-Betrieb muss var/file_inspector/ auf gemeinsam genutztem Speicher liegen, damit alle Knoten denselben Lizenzstatus sehen.

22. Cache-Leerung

Nach einer Aktualisierung des Bundles den Contao-/Symfony-Cache wie üblich leeren:

php bin/console cache:clear

23. Tests

vendor/bin/phpunit

Die Testsuite (PHPUnit 10.5/11.0) deckt unter anderem die Scan-Pipeline, den Papierkorb, den Export-Workflow, Minifizierung, Bildoptimierung sowie die sicherheitskritischen Bereiche der Lizenz- und Berechtigungsverwaltung ab.

24. Fehlerbehebung

Lizenz lässt sich nicht aktivieren: Prüfen, ob mindestens einer Root-Seite dieser Installation eine Domain zugewiesen ist (siehe Lizenzierung).
Deep Scan / Hintergrund-Scan nicht verfügbar: Diese Funktionen erfordern eine Pro-Lizenz.
Minifizierung/Bildoptimierung fehlgeschlagen: Details stehen in var/log/file_inspector/minify.log bzw. var/log/file_inspector/image_optimization.log.
Export & Löschen: Ein Löschvorgang ist niemals endgültig — gelöschte Dateien liegen im Papierkorb und lassen sich dort wiederherstellen.

25. Tatsächliche bekannte Einschränkungen

„Keine Referenz gefunden“ bedeutet, dass in den durchsuchten Quellen keine Referenz erkannt wurde — nicht, dass eine Datei garantiert an keiner Stelle mehr verwendet wird. Zur Laufzeit dynamisch zusammengesetzte Pfade, externe Systeme oder nicht durchsuchte Drittanbieter-Erweiterungen können unentdeckt bleiben. Dafür existiert der Status Unsicher.
Normal Scan durchsucht keine Quelldateien; Referenzen, die ausschließlich im Code oder in Templates liegen, erfordern einen Deep Scan.
Deep Scan überspringt Quelldateien über einer konfigurierbaren Größe (Standard 5 MiB); Anzahl und Gesamtgröße übersprungener Dateien erscheinen im Scan-Bericht.
Ignorierte Ordner und Endungen werden vollständig von jedem Scan ausgeschlossen und nie gemeldet.
Datenbank-Textfelder werden für die Unsicherheitsanalyse nicht erneut durchsucht.

Stets eine Sicherungskopie behalten. Der eingebaute Export & Löschen-Workflow macht dies zum Standardweg.

26. Lizenz- und Urheberrechtsinformationen

Quellcode-Lizenz: LGPL-3.0-or-later. Siehe LICENSE. Copyright: V&T Innovations Team (www.v-t.one).

Die Nutzung der Funktionen dieses Bundles erfordert unabhängig von der Quellcode-Lizenz eine aktivierte Lizenz (siehe Abschnitt 14 und Lizenzierung).

27. Weiterführende Dokumentation

🇬🇧 English README
Lizenzierung — Lizenzmodell, Zustände und Funktionsfreischaltung
Sicherheitsmodell — Schutzmaßnahmen im Überblick
Architektur — technische Dokumentation für Entwicklerinnen und Entwickler, die das Bundle erweitern möchten

vtinnovations / file-inspector

Maintainers

Package info

Statistics

Security