Überblick

File Inspector ist ein Contao-Backend-Modul, das Ihr Upload-Verzeichnis mit allen Referenzen aus Datenbank, Templates und Quellcode abgleicht, für jede Datei offenlegt, warum sie als verwendet oder unverwendet gilt, und das Aufräumen über Papierkorb und ZIP-Export absichert.

Das Problem

Ein Contao-Projekt, das mehrere Jahre gepflegt wird, sammelt Dateien schneller an, als es sie wieder los wird. Bilder werden für eine Kampagne hochgeladen und nach deren Ende nicht entfernt. Ein Redakteur lädt dieselbe Broschüre in drei Varianten hoch und verlinkt eine davon. Ein Relaunch ersetzt eine ganze Bildstrecke, aber niemand löscht die alte, weil niemand sicher sagen kann, ob sie irgendwo noch hängt. Das Verzeichnis files/ wächst, und mit ihm die Unsicherheit.

• Niemand traut sich zu löschen. Die Dateiverwaltung zeigt, was vorhanden ist, aber nicht, ob ein Inhaltselement, ein Stylesheet oder ein Template noch darauf zeigt. Im Zweifel bleibt die Datei liegen — jahrelang.
• Manuelles Nachsehen skaliert nicht. Für eine einzelne Datei kann man die Suche bemühen. Für zwölftausend Dateien ist das keine Aufgabe mehr, sondern ein Projekt.
• Ein Fehlgriff ist teuer. Wer eine noch verwendete Datei löscht, merkt es oft erst, wenn im Frontend ein Bild fehlt — und muss dann Datei und Datenbankeintrag rekonstruieren, damit bestehende Verweise wieder greifen.
• Speicherplatz und Backups wachsen mit. Jedes nächtliche Backup zieht denselben toten Ballast mit, jede Übertragung auf ein Testsystem dauert länger.
• Der Überblick fehlt bei jeder Übergabe. Wechselt die betreuende Agentur oder die Redakteurin, beginnt die Bestandsaufnahme wieder bei null.

Am deutlichsten spürt das, wer die Installation technisch verantwortet und regelmäßig gefragt wird, warum das Backup so groß ist — und keine belastbare Antwort darauf hat, welche Datei entbehrlich wäre.

Die Lösung

Das Grundprinzip in einem Satz: File Inspector erstellt eine Referenzkarte Ihrer Installation und weist für jede einzelne Datei nach, worauf sich die Einstufung stützt — statt sie zu behaupten.

Der Scanner liest die Contao-Datenbank und — im Deep Scan — zusätzlich die Quelldateien des Projekts, und ordnet jede Datei im Upload-Verzeichnis einem von drei Zuständen zu: Referenziert, Unsicher oder Keine Referenzen gefunden. Zu jedem Fund gehört ein Beleg mit Typ, Fundort und Erklärung. Das Löschen selbst ist mehrstufig abgesichert: ein ZIP-Export vor dem Eingriff, ein Papierkorb danach, und eine Wiederherstellung, die den Eintrag in der Dateiverwaltung mitsamt seiner UUID zurückbringt.

Aufgabe	Ohne dieses Paket	Mit File Inspector
Herausfinden, ob eine Datei noch verwendet wird	Manuelle Suche in Backend, Templates und CSS — pro Datei	Ein Scan über den gesamten Bestand, mit Beleg je Datei
Nachvollziehen, wo eine Datei verwendet wird	Nicht systematisch möglich	Verwendungs-Explorer mit Tabelle, Datensatztitel und Bearbeiten-Link
Umgang mit unklaren Fällen	Bauchgefühl	Eigener Status Unsicher mit Fundstelle und Begründung
Löschen	Endgültig, ohne Netz	ZIP-Export, dann Papierkorb, jederzeit wiederherstellbar
Wiederherstellung nach einem Fehlgriff	Datei zurückspielen, Datenbankeintrag von Hand reparieren	Ein Klick — Datei und Dateiverwaltungs-Eintrag kehren zurück
Nachvollziehbarkeit	Keine	Jeder Scan wird gespeichert, jede Löschung protokolliert

Den oben genannten Problemen stehen konkret gegenüber:

• Normal Scan und Deep Scan ersetzen das manuelle Nachsehen.
• Belege und der Datei-Verwendungs-Explorer machen jede Einstufung überprüfbar.
• Export & Löschen und der Papierkorb nehmen dem Löschen das Risiko.
• Scan-Verlauf und die Protokolle halten fest, was wann geschah.
• Minifizieren und Bilder optimieren verkleinern, was bleiben soll.

Wann das Paket passt

Situation	Einschätzung
Gewachsene Contao-Installation mit tausenden Dateien in files/	Der Kernfall. Genau dafür ist das Paket gebaut.
Nach einem Relaunch soll der Altbestand bereinigt werden	Gut geeignet — Deep Scan, dann Export & Löschen mit Papierkorb als Netz.
Sie möchten vor einer Migration wissen, was Sie tatsächlich mitnehmen müssen	Geeignet. Der Scan-Bericht beziffert das Einsparpotenzial.
Sie brauchen nur eine Liste großer Dateien	Überdimensioniert. Dafür genügt die Contao-Dateiverwaltung.
Dateien werden überwiegend aus zur Laufzeit zusammengesetzten Pfaden geladen	Nicht dieses Paket. Statische Analyse kann solche Referenzen nicht auflösen; fast alles landet dann unter Unsicher und Sie prüfen weiterhin von Hand.
Dateien werden hauptsächlich von externen Systemen ausgeliefert (CDN, Newsletter-Versand, Drittanbieter-App)	Nur mit Vorbehalt. Diese Referenzen sieht der Scanner grundsätzlich nicht — die Einstufung „Keine Referenzen gefunden“ wäre dort irreführend.
Sie erwarten eine automatische Bereinigung ohne Sichtprüfung	Nicht dieses Paket. Es gibt bewusst keinen Automatismus, der ohne Ihre Auswahl löscht.

Teil 1 — Einrichtung

Der Weg von der Installation bis zum ersten auswertbaren Ergebnis:

1. Voraussetzungen prüfen
2. Vor der Installation: Sicherung und Schreibrechte
3. Installation über den Contao Manager — oder über Composer
4. Installation überprüfen
5. Lizenz aktivieren
6. Ignorierregeln anpassen (optional, Pro)
7. Der erste Scan

Voraussetzungen

Aus der composer.json des Pakets:

Komponente	Anforderung	Anmerkung
PHP	^8.2	—
Contao	contao/core-bundle ^5.3	—
Symfony	^6.4 || ^7.0	Config, DI, Event-Dispatcher, Finder, HTTP-Client, HTTP-Foundation, HTTP-Kernel, Routing
Doctrine DBAL	^3.6 || ^4.0	—
matthiasmullie/minify	^1.3	Wird über Composer mitinstalliert
PHP-Erweiterung curl	erforderlich	—
PHP-Erweiterung pdo	erforderlich	—
PHP-Erweiterung sodium	erforderlich	—
PHP-Erweiterung zip	faktisch erforderlich für den ZIP-Export	Wird von Composer nicht erzwungen. Ohne sie schlägt jeder Export fehl, der übrige Funktionsumfang bleibt nutzbar.
PHP-Erweiterung gd	für Bilder optimieren	Von Contao ohnehin vorausgesetzt. Ob WebP und AVIF geschrieben werden können, hängt vom konkreten Build ab.
PHP-Erweiterung imagick	optional	Notwendig, um SVG als Quellformat zu konvertieren. Für WebP und AVIF wird sie bevorzugt, wenn vorhanden.

Das Paket bringt keine Konfigurationsdatei mit, die Sie anlegen müssten. Alles, was einstellbar ist, wird im Backend eingestellt.

Vor der Installation

Sicherung

Legen Sie eine Sicherung von Datenbank und Dateisystem an. Das Paket führt Datenbankmigrationen aus und schreibt später in Ihr Upload-Verzeichnis — beides Gründe, vorher einen Wiederherstellungspunkt zu haben.

Schreibrechte

Der PHP-Prozess braucht Schreibzugriff auf folgende Ablagen unterhalb von var/. Alle werden bei Bedarf automatisch angelegt; keine liegt im öffentlichen Webverzeichnis.

Ablage	Inhalt	Gehört in die Datensicherung
var/fi_scans/	Vollständige Scan-Ergebnisse als JSON, eine Datei je Scan	Empfehlenswert
var/fi_scan_jobs/	Zwischenstand laufender Hintergrund-Scans	Nein
var/fi_exports/	Noch nicht bestätigte Export-&-Löschen-Vorgänge	Nein
var/fi_bin/	Die Dateiinhalte im Papierkorb	Ja
var/fi_minify_backups/	Originale, die vor dem Minifizieren kopiert wurden	Ja
var/fi_settings.json	Ignorierregeln	Ja
var/fi_retention.json	Aufbewahrungseinstellung des Scan-Verlaufs	Ja
var/fi_minified.json	Vermerk, welche Datei bereits minifiziert wurde	Ja
var/log/file_inspector/	Protokolle zu Löschungen, Minifizierung und Bildkonvertierung	Ja
Ein privates Verzeichnis unterhalb von var/	Lizenzdaten	Ja — muss für den Webserver beschreibbar sein

Zu klärende Fragen

• Welche Ordner sollen grundsätzlich ausgenommen bleiben? Ab Werk werden die Ordner archive, backup, import, old und legacy sowie die Endungen php, phar und phtml übersprungen. Siehe Ignorierregeln.
• Steht ein Testsystem zur Verfügung? Der erste Deep Scan einer großen Installation lässt sich dort risikofrei zeitlich einordnen.
• Ist für die Startseite eine Domain hinterlegt? Ohne konfigurierte Domain lässt sich keine Lizenz aktivieren — siehe Lizenz aktivieren.

Installation über den Contao Manager

Der empfohlene Weg.

1. Contao Manager öffnen und anmelden.
2. Bereich Entdecken öffnen. Neue Pakete werden immer dort gesucht und hinzugefügt; der Bereich Pakete daneben zeigt unter Installierte Pakete nur, was bereits vorhanden ist. Entdecken ist zugleich die Startansicht.
3. Über Pakete suchen nach vtinnovations/file-inspector suchen und beim Treffer Paket hinzufügen wählen.
4. Änderungen anwenden. Der Contao Manager installiert das Paket und aktualisiert den Autoloader. Der Manager meldet dazu: „Dieses Paket wird installiert, wenn du die Änderungen anwendest.“
5. Bereich Systemwartung → Datenbank-Migrationen und -Backups → Datenbank prüfen; die angezeigten Datenbank-Änderungen bestätigen. Das Paket legt dabei die Tabellen tl_fi_scan und tl_fi_bin an.
6. Unter Systemwartung den Anwendungs-Cache leeren (in der Navigation auch als Cache erneuern).

Installation über Composer

Die Alternative auf der Kommandozeile:

composer require vtinnovations/file-inspector

Anschließend die Migrationen ausführen:

php bin/console contao:migrate

Bei einer Managed Edition zusätzlich:

php bin/console contao:setup

Eine spätere Aktualisierung:

composer update vtinnovations/file-inspector
php bin/console contao:migrate
php bin/console cache:clear

Eine manuelle Bundle-Registrierung ist nicht nötig: Das Paket ist als contao-bundle deklariert und meldet sich über sein Contao-Manager-Plugin selbst an.

Installation überprüfen

1. Prüfen, dass keine Migration mehr aussteht:

   php bin/console contao:migrate --dry-run

   Gemeldet werden dürfen keine offenen Änderungen an tl_fi_scan oder tl_fi_bin.
2. Im Contao-Backend die Gruppe System aufklappen. Dort erscheint File Inspector mit der Beschreibung „Findet Dateien im Dateisystem, die in der Datenbank nicht referenziert sind.“
3. Erscheint der Eintrag nicht, ist er der Benutzergruppe nicht zugewiesen: unter System → Benutzergruppen das Modul File Inspector freigeben — wie bei jedem anderen Backend-Modul.
4. Das Modul öffnen. Ohne aktive Lizenz erscheint an dieser Stelle der Hinweis „Dieses Plugin benötigt eine Lizenz. Aktivieren Sie sie unter Contao → Einstellungen → File Inspector Licence management.“ Das ist der erwartete Zustand vor Schritt Lizenz aktivieren.

Lizenz aktivieren

File Inspector benötigt eine aktivierte Lizenz — auch für die kostenlose Stufe. Ohne gültige Lizenz öffnet das Modul keine seiner Ansichten und zeigt stattdessen den oben genannten Hinweis. Es werden dabei keinerlei Dateien verändert oder gelöscht.

Verwaltet wird die Lizenz ausschließlich unter Contao → Einstellungen, im Abschnitt V-T.ONE Licence management, dort unter der Überschrift File Inspector („Die File-Inspector-Lizenz dieser Installation aktivieren, aktualisieren oder entfernen.“). Innerhalb des Moduls gibt es keine Lizenzseite; der Navigationspunkt 🔑 Lizenz verweist lediglich dorthin.

So aktivieren Sie die Lizenz

1. Sicherstellen, dass für mindestens eine Startseite dieser Installation eine Domain hinterlegt ist. Fehlt sie, meldet der Abschnitt: „Für keine Startseite ist eine Domain konfiguriert, daher kann keine Lizenz aktiviert werden. Bitte zuerst die Domain der Startseite eintragen.“
2. Als Administrator anmelden und Contao → Einstellungen öffnen.
3. Ganz oben den Abschnitt V-T.ONE Licence management aufsuchen und darin den Block File Inspector.
4. Den Lizenzschlüssel in das Feld Lizenzschlüssel eintragen. Der Platzhalter zeigt das erwartete Format: XXXXX-XXXXX-XXXXX-XXXXX.
5. Verify and Activate Licence anklicken. Der Server nimmt dazu selbst eine ausgehende HTTPS-Verbindung auf — nicht Ihr Browser. Die Anfrage läuft synchron: Lassen Sie den Tab geöffnet, bis die Seite neu aufgebaut ist.
6. Die Statuszeile über dem Feld prüfen. Bei Erfolg steht dort „Pro-Lizenz aktiv“ beziehungsweise „Kostenlose Lizenz aktiv“.
7. Zurück nach System → File Inspector. Das Modul öffnet nun seine Startseite mit der Auswahl des Scan-Modus.

Die Bedienelemente des Abschnitts

Element	Bedeutung
Schlüssel	Der hinterlegte Schlüssel, nur maskiert dargestellt. Zum Ändern geben Sie ihn erneut vollständig ein.
Paket	Die aktive Lizenzstufe.
Gültig ab / Gültig bis	Laufzeit. Eine unbefristete Lizenz zeigt „unbegrenzt“.
Zuletzt geprüft	Zeitpunkt der letzten Prüfung; „nie“, solange noch keine stattgefunden hat.
Lizenzschlüssel	Das Eingabefeld. Platzhalter XXXXX-XXXXX-XXXXX-XXXXX.
Verify and Activate Licence	Aktiviert den eingegebenen Schlüssel für diese Installation.
Update Licence	Holt den aktuellen Stand einer bereits aktivierten Lizenz — etwa nach einem Upgrade oder einer Verlängerung.
Remove Licence	Entfernt die Lizenz. Es erscheint die Rückfrage „Die Lizenz von dieser Installation entfernen? File Inspector sperrt seine Funktionen, bis eine neue Lizenz aktiviert wird.“

Domainbindung

Eine Lizenz gilt für die Hostnamen, die in den Startseiten dieser Installation eingetragen sind — exakt und ohne Platzhalter. example.com und www.example.com sind zwei verschiedene Identitäten. Ein Testsystem unter einer anderen Domain benötigt daher eine eigene Freigabe.

Was die Lizenzstufe freischaltet

Funktion	Free	Pro
Modul öffnen, Normal Scan	Ja	Ja
Deep Scan einschließlich Unsicherheitsanalyse	Nein	Ja
Hintergrund-Scan mit Fortschrittsanzeige	Nein — der Normal Scan läuft stattdessen synchron	Ja
Belege ansehen (Evidence Viewer)	Ja	Ja
Datei-Verwendungs-Explorer	Ja	Ja
Scan-Verlauf ansehen	Ja	Ja
Einzelnen Scan löschen, Aufbewahrung einstellen	Nein	Ja
ZIP-Export, Export & Löschen, Löschen	Nein	Ja
Papierkorb: ansehen, wiederherstellen, leeren	Ja	Ja
Ignorierregeln bearbeiten	Nein	Ja
CSS/JS minifizieren	Nein	Ja
Bilder optimieren	Nein	Ja

In der Praxis heißt das: Mit einer kostenlosen Lizenz können Sie Ihren Dateibestand vollständig analysieren und nachvollziehen — verändern können Sie ihn damit nicht. Das Aufräumen selbst, das Minifizieren, die Bildkonvertierung und die Ignorierregeln setzen Pro voraus. Der Papierkorb bleibt in beiden Fällen erreichbar, damit bereits gelöschte Dateien auch nach Ablauf einer Pro-Lizenz noch zurückgeholt werden können.

Der erste Scan

1. System → File Inspector öffnen. Die Startseite trägt die Beschreibung: „Durchsucht das Upload-Verzeichnis und vergleicht jede Datei mit allen Referenzen aus Datenbank, Inhaltsfeldern und Quellcode. Wählen Sie einen Scan-Modus, um zu beginnen.“
2. Den Modus wählen. Normal Scan ist mit Empfohlen gekennzeichnet, Deep Scan mit Gründlich. Ohne Pro-Lizenz trägt Deep Scan die Markierung 🔒 Pro und lässt sich nicht starten.
3. ▶ Scan starten anklicken.
4. Mit Pro erscheint eine Fortschrittsanzeige mit den Phasen „Referenzen einsammeln“, „CSS-Abhängigkeitsgraph aufbauen“, „Upload-Verzeichnis scannen“, „Unsicherheiten analysieren“ und „Ergebnisse speichern“, jeweils mit Zähler. Der Scan kann jederzeit über Scan abbrechen beendet werden.
   Ohne Pro läuft der Normal Scan in einer einzigen, blockierenden Anfrage. Ein Überlagerungsfenster meldet „Dateien werden gescannt…“. Schließen Sie den Tab in dieser Zeit nicht — die Anfrage bricht sonst ab, und der Scan wird nicht gespeichert.
5. Nach Abschluss erscheint der Bericht mit den Kennzahlen Gescannte Dateien, Referenziert, Unsicher, Keine Referenzen und Einsparpotenzial.
6. Den Abschnitt „Über diesen Scanner & bekannte Einschränkungen“ unterhalb der Ergebnisse einmal vollständig lesen. Er benennt, was die statische Analyse grundsätzlich nicht sehen kann.
7. Noch nichts löschen. Prüfen Sie zunächst über Belege und den Verwendungs-Explorer einige Stichproben aus der Gruppe „Keine Referenzen gefunden“.

Teil 2 — Funktionen im Detail

Alle Funktionen liegen im Backend-Modul System → File Inspector und sind über dessen Navigationsleiste erreichbar: 🔍 File Inspector, 🔎 Verwendung, 🗜 Minifizieren, 🖼 Bilder optimieren, 🕐 Verlauf, 🗑 Papierkorb, ⚙ Ignorierregeln und 🔑 Lizenz.

Normal Scan

Der schnelle Modus. Er wertet ausschließlich die Datenbank aus und ist auf jeder Lizenzstufe verfügbar, auch der kostenlosen. Zu finden auf der Startseite des Moduls als erste der beiden Modus-Karten, gekennzeichnet mit Empfohlen.

Er sammelt Referenzen aus zwei Quellen:

• DCA-Dateifelder — jede Spalte, die als Dateiauswahl definiert ist. Ein hier ausgewähltes Bild gilt damit als referenziert.
• HTML- und Textinhalte — Insert-Tags wie und , HTML-Attribute (src, href, data-*), url()-Aufrufe in CSS und ausgeschriebene Upload-Pfade in Textareas, Code- und Rich-Text-Feldern.

So führen Sie einen Normal Scan aus

1. System → File Inspector öffnen.
2. Die Karte Normal Scan auswählen.
3. ▶ Scan starten anklicken.
4. Ohne Pro-Lizenz erscheint die Meldung „Dateien werden gescannt…“ und die Anfrage blockiert bis zum Ende. Mit Pro läuft der Scan im Hintergrund mit Fortschrittsanzeige.
5. Die Kennzahlenkarten oberhalb der Ergebnistabelle auswerten.
6. In der Spalte Status die Einstufung jeder Datei ablesen und über Belege anzeigen beziehungsweise Warum? in die Einzelheiten wechseln.

Deep Scan

Alles aus dem Normal Scan, zusätzlich eine Durchsuchung der Projekt-Quelldateien. Der Modus ist auf der Startseite als zweite Karte mit Gründlich gekennzeichnet und erfordert eine Pro-Lizenz; ohne sie trägt die Karte die Markierung 🔒 Pro.

Zusätzlich zum Normal Scan liefert er:

• Quelldatei-Referenzen aus src/, templates/, config/, vendor/ und public/ — untersucht werden unter anderem PHP, Twig, HTML, JavaScript, TypeScript, CSS, SCSS, LESS, JSON, YAML, XML und SVG.
• CSS-Abhängigkeitsauflösung — @import-, @use-, @forward- und url()-Ketten werden transitiv verfolgt. Eine Teildatei, die nur von einem anderen Stylesheet eingebunden wird, gilt dadurch weiterhin als verwendet.
• Unsicherheitsanalyse — siehe Statuswerte, Belege und Unsicherheit.

So führen Sie einen Deep Scan aus

1. Sicherstellen, dass eine Pro-Lizenz aktiv ist (Statuszeile: „Pro-Lizenz aktiv“).
2. System → File Inspector öffnen.
3. Die Karte Deep Scan auswählen.
4. ▶ Scan starten anklicken.
5. Die Fortschrittsanzeige durchläuft die Phasen in fester Reihenfolge: „Referenzen einsammeln“ → „CSS-Abhängigkeitsgraph aufbauen“ → „Upload-Verzeichnis scannen“ → „Unsicherheiten analysieren“ → „Ergebnisse speichern“.
6. Läuft bereits ein anderer Scan, erscheint „Ein Scan läuft bereits“ mit der Erklärung „Ein anderer Scan ist aktiv. Sie können ihn weiter verfolgen oder abbrechen und einen neuen starten.“ — dann Scan fortsetzen oder Neuen Scan starten wählen.
7. Im Bericht die Karte Übersprungene Quelldateien beachten. Sie zeigt an, wie viele Quelldateien wegen Überschreitung des Größenlimits ausgelassen wurden („Größenlimit für Deep Scan überschritten“).

Statuswerte, Belege und Unsicherheit

Jede Datei erhält genau einen von drei Status. Die Legende unter der Ergebnistabelle nennt sie kurz; ausführlich stehen sie im aufklappbaren Abschnitt „So funktioniert der Scanner & seine Einschränkungen“ auf der Startseite.

Status	Bedeutung laut Oberfläche	Kurzfassung in der Legende
Referenziert	„Mindestens eine bestätigte Referenz wurde gefunden: ein DCA-Dateiauswahl-Feld, ein Insert-Tag, ein HTML-Attribut, ein CSS-url() oder @import oder ein wörtlicher Pfad in einer Quelldatei. Diese Dateien sollten nicht gelöscht werden.“	„Bestätigte Referenz gefunden — nicht löschen.“
Unsicher	„Es wurde keine bestätigte Referenz gefunden, aber der Dateiname (oder ein partieller Pfad) erscheint im Quellcode in einem dynamischen oder mehrdeutigen Kontext, der statisch nicht aufgelöst werden kann. Bitte manuell prüfen, bevor Sie handeln.“	„Erscheint dynamisch im Quellcode — vor dem Löschen prüfen.“
Keine Referenzen gefunden	„Es wurde keinerlei Referenz erkannt. Diese Dateien sind die primären Löschkandidaten — dennoch wird eine abschließende manuelle Prüfung vor dem Entfernen empfohlen.“	„Keine Referenz erkannt — Löschkandidat.“

So prüfen Sie die Belege einer einzelnen Datei

1. Im Scan-Bericht die Zeile der Datei aufsuchen.
2. Bei einer referenzierten Datei Belege anzeigen anklicken; die Zahl in Klammern nennt die Anzahl der Fundstellen.
3. Bei einer als unsicher eingestuften Datei Warum unsicher? anklicken, bei einer Datei ohne Referenz Warum?.
4. Alternativ öffnet Details den Nachweis-Dialog Datei-Nachweis. Er zeigt Status, Größe, Änderungsdatum, die DBAFS-UUID und die Abschnitte Gefundene Referenzen, Unsicherheitsindikatoren beziehungsweise Analyseergebnis.
5. Jeden Beleg an seinem Typ ablesen — etwa „In einem Dateiauswahlfeld ausgewählt“, „Über ein Datei-Insert-Tag eingebunden“, „Im Seiteninhalt verlinkt oder eingebettet“, „Aus einem Stylesheet referenziert“, „Von einem Stylesheet importiert“ oder „Über den Dateipfad erwähnt“.
6. Bei Bedarf Technische Details aufklappen: Quelle, Treffertyp und gefundener Wert.
7. Mit Schließen zurück zur Liste.

Was der Scanner grundsätzlich nicht sieht

Wörtlich aus dem Hinweisfeld des Moduls:

• „Pfade, die zur Laufzeit aus Variablen oder Konfigurationswerten zusammengesetzt werden“
• „Dateien, die nur von externen Systemen referenziert werden (CDN, E-Mail-Kampagnen, Drittanbieter-Apps)“
• „UUIDs in benutzerdefinierten Tabellen ohne DCA-fileTree-Felddefinition“
• „Dateien in Contao-Extensions mit nicht-standardisierter Referenzspeicherung“
• „Dateien, die nach dem Scan-Zeitpunkt in das Upload-Verzeichnis hinzugefügt wurden“

Datei-Verwendungs-Explorer

Zeigt für eine einzelne Datei jede bekannte Fundstelle und führt von dort direkt in den zu bearbeitenden Datensatz. Erreichbar über 🔎 Verwendung. Auf jeder Lizenzstufe verfügbar.

Die Ansicht arbeitet ausschließlich mit den Daten des zuletzt gespeicherten Scans: „Die Ergebnisse stammen aus dem letzten Scan — es wird nichts neu gescannt.“ Ohne vorhandenen Scan erscheint „Noch keine Scan-Daten“ mit der Aufforderung, zuerst einen Scan auszuführen.

So finden Sie heraus, wo eine Datei verwendet wird

1. In der Navigationsleiste 🔎 Verwendung öffnen.
2. Im Feld Nach Dateiname oder Pfad suchen einen Teil des Namens oder Pfades eingeben — der Platzhalter nennt als Beispiel z. B. logo.png oder files/images/.
3. 🔎 Suchen anklicken.
4. In der Tabelle Passende Dateien die gewünschte Zeile aufsuchen. Die Spalte Verwendung zeigt bereits „An 1 Stelle verwendet“, „An %s Stellen verwendet“ oder „Keine Referenzen gefunden“.
5. Verwendung anzeigen → anklicken.
6. Die Detailansicht durchgehen: Dateiinformationen, Verwendungsübersicht, Datenbank-Referenzen, Template-Referenzen und Quellcode-Referenzen.
7. Bei einer Datenbank-Referenz zeigt Wo zu finden die Kette der übergeordneten Datensätze (etwa Seite → Artikel → Inhaltselement). ✎ Bearbeiten öffnet den Datensatz — der Hinweis „Öffnet in einem neuen Tab“ steht daneben.
8. Bei Template- und Quellcode-Referenzen den Pfad mit ⧉ Pfad kopieren übernehmen; die Rückmeldung lautet „Kopiert!“.
9. Über Zurück zur Suche die nächste Datei prüfen.

Aufräumen: ZIP-Export, Export & Löschen, Löschen

Die eigentliche Bereinigung. Sie findet in der Ergebnistabelle eines Scans statt, über die drei Schaltflächen rechts in der Werkzeugleiste, und erfordert eine Pro-Lizenz. Mit einer kostenlosen Lizenz sehen Sie die Ergebnisse vollständig, können aber keine Datei exportieren oder entfernen.

Schaltfläche	Verhalten
📦 ZIP-Export	Erstellt ein ZIP-Archiv der Auswahl und lädt es herunter. Es wird nichts gelöscht.
📦🗑 Export & Löschen	Der abgesicherte Weg: Export, Download und Löschung laufen in drei getrennten Anfragen. Ohne die ausdrückliche Bestätigung im letzten Schritt wird nichts entfernt.
🗑 Löschen	Verschiebt die Auswahl sofort in den Papierkorb — ohne Rückfrage und ohne vorherigen Export.

Zur Auswahl dienen die Schaltflächen Alle, Keine, Unreferenziert und — sofern unsichere Dateien vorliegen — + Unsicher. Solange nichts ausgewählt ist, steht dort „Nichts ausgewählt“ und die drei Aktionen bleiben deaktiviert.

So gehen Sie mit Export & Löschen vor

1. Einen Scan ausführen oder über 🕐 Verlauf einen gespeicherten Scan öffnen.
2. Die zu entfernenden Dateien auswählen. Unreferenziert wählt alle Dateien ohne Referenz auf einmal.
3. Enthält die Auswahl unsichere Dateien, erscheint der Warnhinweis: „n UNSICHER Datei(en) in Ihrer Auswahl. Diese erscheinen im Quellcode dynamisch — das Löschen kann Ihre Anwendung beschädigen.“ Prüfen Sie diese Dateien einzeln, bevor Sie fortfahren.
4. 📦🗑 Export & Löschen anklicken. Es erscheint die Seite Export & Löschen mit der Meldung „Export erfolgreich erstellt.“ und dem Zusatz „Ein ZIP-Archiv der ausgewählten Dateien wurde auf Ihren Computer heruntergeladen. Es wurden noch keine Dateien gelöscht.“
5. Den Download prüfen. Startet er nicht selbst, steht dort „Ihr Download sollte automatisch starten. Falls nicht,“ — gefolgt vom Link „hier klicken, um den Export herunterzuladen“.
6. Die heruntergeladene Datei öffnen und den Inhalt stichprobenartig kontrollieren. Das ist der letzte Moment, in dem das folgenlos möglich ist.
7. Zum Löschen 🗑 In den Papierkorb verschieben anklicken und die Rückfrage „n Dateien in den Papierkorb verschieben?“ bestätigen.
8. Zum Abbrechen stattdessen ✕ Abbrechen wählen. Die Meldung lautet dann „‚Export & Löschen‘ abgebrochen. Es wurden keine Dateien gelöscht.“
9. Nach dem Löschen führt das Modul einen frischen Scan im selben Modus aus und meldet „n Datei(en) (Größe) in den Papierkorb verschoben. Vor dem Löschen wurde ein ZIP-Export heruntergeladen.“

Ein wartender Export & Löschen-Vorgang verfällt nach 30 Minuten. Danach erscheint „Export nicht gefunden oder abgelaufen. Bitte führen Sie ‚Export & Löschen‘ erneut aus.“ — es wurde in diesem Fall nichts gelöscht.

Papierkorb

Alles, was die Aufräum-Werkzeuge löschen, landet zuerst hier. Erreichbar über 🗑 Papierkorb; die Navigationsleiste zeigt die Anzahl als Zähler an. Auf jeder Lizenzstufe verfügbar — auch nach Ablauf einer Pro-Lizenz kommen Sie an Ihre gelöschten Dateien.

Die Seite beschreibt es selbst: „Gelöschte Dateien bleiben hier, bis Sie sie entfernen. Beim Wiederherstellen wird eine Datei an ihren ursprünglichen Ort zurückgelegt und ihr Datensatz im Dateimanager wiederhergestellt, sodass bestehende Verweise weiter funktionieren.“ Ein automatischer Ablauf findet nicht statt.

So stellen Sie eine gelöschte Datei wieder her

1. 🗑 Papierkorb öffnen.
2. Die gewünschten Einträge ankreuzen — oder Alle auswählen verwenden. Jede Zeile zeigt neben Pfad und Größe auch die frühere Einstufung: „war referenziert“, „unsicher“ oder „keine Verweise“.
3. ↩ Auswahl wiederherstellen anklicken (bei einer einzelnen Zeile: ↩ Wiederherstellen).
4. Ist der ursprüngliche Pfad inzwischen wieder belegt, erscheint die Seite Wiederherstellungskonflikte lösen: „n der ausgewählten Dateien existieren bereits an ihrem ursprünglichen Ort. Wählen Sie, ob das Vorhandene ersetzt oder die Wiederherstellung übersprungen werden soll. Nicht betroffene Dateien werden in jedem Fall wiederhergestellt.“
5. Je Konflikt ♻ Vorhandene ersetzen oder ⏭ Überspringen wählen — oder über Auf alle anwenden: mit Alle ersetzen beziehungsweise Alle überspringen pauschal entscheiden.
6. Mit ↩ Wiederherstellen abschließen.
7. Die Rückmeldung prüfen: „n Datei(en) wiederhergestellt.“, gegebenenfalls ergänzt um „n Datei(en) übersprungen.“

So leeren Sie den Papierkorb

1. 🗑 Papierkorb öffnen.
2. Für einzelne Einträge: ankreuzen und 🗑 Auswahl löschen anklicken, dann die Rückfrage „Die ausgewählten Dateien endgültig löschen? Dies kann nicht rückgängig gemacht werden.“ bestätigen.
3. Für alles: 🗑 Papierkorb leeren anklicken und „ALLE Dateien im Papierkorb endgültig löschen? Dies kann nicht rückgängig gemacht werden.“ bestätigen.
4. Die Bestätigung lautet „Papierkorb geleert — n Datei(en) endgültig gelöscht.“

Scan-Verlauf und Aufbewahrung

Jeder abgeschlossene Scan wird automatisch gespeichert. Der Verlauf ist über 🕐 Verlauf erreichbar und auf jeder Lizenzstufe einsehbar. Das Löschen einzelner Scans und die Aufbewahrungseinstellung erfordern dagegen Pro.

So arbeiten Sie mit dem Verlauf

1. 🕐 Verlauf öffnen. Die Kopfzeile nennt die Anzahl gespeicherter Scans.
2. Über Scans durchsuchen…, den Filter Modus (Alle, Normal, Tief) und Sortieren (Neueste zuerst, Älteste zuerst, Längste Dauer, Meiste ohne Referenz) die Liste eingrenzen.
3. Mit ↗ Details die Detailseite eines Scans öffnen. Sie zeigt Kennzahlen, den Abschnitt Scan-Details (Scan-ID, Modus, Status, Benutzer, Ergebnisdatei), Zeitangaben und Scan-Konfiguration zum Zeitpunkt der Ausführung.
4. Über ↗ Vollständige Ergebnisse anzeigen die komplette Ergebnistabelle des damaligen Laufs erneut öffnen — ohne neu zu scannen.
5. Weichen die heute aktiven Ignorierregeln von den damals verwendeten ab, weist die Detailseite darauf hin: „Die aktiven Ignorierregeln weichen von der für diesen Scan verwendeten Konfiguration ab. Ein neuer Scan würde andere Regeln verwenden und möglicherweise andere Ergebnisse liefern.“
6. Pro: Einen Scan mit 🗑 Löschen entfernen und „Scan #%d endgültig löschen? Dies kann nicht rückgängig gemacht werden.“ bestätigen.

So stellen Sie die automatische Aufbewahrung ein (Pro)

1. 🕐 Verlauf öffnen.
2. Das Kästchen Scans automatisch löschen, die älter sind als ankreuzen.
3. Im Feld daneben die Anzahl der Tage, für die Scans aufbewahrt werden eintragen. Voreinstellung: 30 Tage (zulässig sind 1 bis 3650).
4. 💾 Speichern anklicken.
5. Die Bestätigung lautet „Einstellungen zur Verlaufsaufbewahrung gespeichert.“ Die Regel wird sofort angewendet, die Liste erscheint bereits bereinigt.

Regel	Wert	Einstellbar
Höchstzahl aufbewahrter Scans	50	Nein — feste Obergrenze
Altersgrenze	30 Tage, aktiv	Ja, auf der Verlaufsseite (Pro)
Länge der angezeigten Liste	die 30 jüngsten Scans	Nein

Ignorierregeln

Legt fest, welche Ordner und Dateiendungen bei jedem Scan übersprungen werden. Erreichbar über ⚙ Ignorierregeln; erfordert eine Pro-Lizenz. Die Seite trägt den Titel Ignorierregeln konfigurieren und den Hinweis: „Dateien und Ordner, die diesen Regeln entsprechen, werden bei allen Scans übersprungen. Änderungen gelten ab dem nächsten Scan-Lauf.“

Bereich	Bedeutung	Voreinstellung
Ignorierte Ordner	„Ein Ordnername pro Eintrag, abgeglichen mit dem ersten Segment des upload-relativen Pfades (z. B. archive überspringt files/archive/**). Wildcard-Muster werden unterstützt.“	archive, backup, import, old, legacy
Ignorierte Dateiendungen	„Endungen ohne führenden Punkt eingeben (z. B. php, nicht .php). Wildcard-Muster wie ph* werden unterstützt.“	php, phar, phtml

Unterstützt werden exakte Namen und Wildcards: „* entspricht einer beliebigen Zeichenfolge, ? einem einzelnen Zeichen, [abc] einer Zeichenklasse. Reguläre Ausdrücke werden noch nicht unterstützt.“

So passen Sie die Regeln an

1. ⚙ Ignorierregeln öffnen.
2. Im Abschnitt Ignorierte Ordner unter Ordnername oder Muster hinzufügen… den Eintrag eingeben und + Hinzufügen anklicken.
3. Für Dateiendungen ebenso unter Dateiendung hinzufügen (ohne Punkt)… verfahren.
4. Nicht mehr gewünschte Einträge mit Entfernen löschen.
5. 💾 Einstellungen speichern anklicken.
6. Die Bestätigung lautet „Ignorierregeln erfolgreich gespeichert.“ Die Marke angepasst zeigt fortan, dass von der Voreinstellung abgewichen wird.
7. Zum Zurücksetzen ↺ Auf Standard zurücksetzen anklicken und „Alle Ignorierregeln auf Standard zurücksetzen? Alle benutzerdefinierten Einstellungen gehen verloren.“ bestätigen.

Ungültige Einträge werden beim Speichern abgewiesen. Die Prüfungen im Einzelnen:

Meldung	Ursache
„Pfad-Traversierung nicht erlaubt“	Der Eintrag enthält ..
„Darf nicht mit / beginnen“	Führender Schrägstrich
„Ungültiges Zeichen (Null-Byte)“	Null-Byte im Eintrag
„Zu lang (max. 128 Zeichen)“	Ordnername länger als 128 Zeichen
„Ungültige Zeichen — erlaubt: Buchstaben, Ziffern, -, _, ., *, ?, [, ]“	Unzulässiges Zeichen im Ordnernamen
„Erweiterung darf nicht leer sein“	Leerer Endungs-Eintrag
„Zu lang (max. 20 Zeichen)“	Endung länger als 20 Zeichen
„Ungültige Zeichen — erlaubt: Buchstaben, Ziffern, -, _, *, ?“	Unzulässiges Zeichen in der Endung

CSS und JS minifizieren

Verkleinert CSS- und JavaScript-Dateien im Upload-Verzeichnis. Erreichbar über 🗜 Minifizieren; erfordert eine Pro-Lizenz.

Die Seite erklärt ihr Verhalten selbst: „Jede .css- und .js-Datei in Ihrem Upload-Verzeichnis, unabhängig davon, ob sie derzeit referenziert wird. Ausgewählte Dateien werden direkt minifiziert — der ursprüngliche Inhalt wird ersetzt, es wird keine neue Datei erstellt. Das Original wird zuvor intern gesichert, sodass ein fehlerhaftes Ergebnis manuell wiederhergestellt werden kann.“

Minifiziert werden ausschließlich Leerzeichen und Kommentare. Variablen werden nicht umbenannt, es findet keine Umformung statt, die das Verhalten ändern könnte.

So minifizieren Sie Dateien

1. 🗜 Minifizieren öffnen. Die Liste enthält jede CSS- und JS-Datei des Upload-Verzeichnisses.
2. Über Nach Dateiname oder Pfad suchen… und die Ordnerauswahl (Alle Ordner) eingrenzen.
3. Die gewünschten Dateien ankreuzen oder Alle auswählen verwenden. Bereits verkleinerte Dateien tragen die Marke ✓ bereits minifiziert.
4. 🗜 Ausgewählte Dateien minifizieren anklicken.
5. Die Rückmeldungen auswerten: „%d Datei(en) minifiziert, %s eingespart.“, gegebenenfalls „%d Datei(en) waren bereits minimal und wurden nicht verändert.“
6. Das Ergebnis im Frontend prüfen — die betroffenen Seiten aufrufen und Layout wie Skriptverhalten kontrollieren, solange Sie noch wissen, welche Dateien Sie angefasst haben.

Bilder optimieren

Erzeugt aus vorhandenen Bildern eine Fassung in einem moderneren Format. Erreichbar über 🖼 Bilder optimieren; erfordert eine Pro-Lizenz.

Die Seite beschreibt die Zusicherung, auf die es ankommt: „Jede Bilddatei in Ihrem Upload-Verzeichnis. Ausgewählte Dateien werden als neue Datei im gewählten Format am selben Ort erstellt — das Original wird niemals verändert, ersetzt oder gelöscht.“

Richtung	Formate	Bedingung
Quellformate	JPG, JPEG, PNG, GIF, WebP, BMP, SVG	SVG nur mit Imagick samt SVG-Unterstützung
Zielformat WebP	—	Verfügbar, wenn GD oder Imagick WebP schreiben kann
Zielformat AVIF	—	Verfügbar, wenn GD oder Imagick AVIF schreiben kann
Zielformat ICO	—	Immer verfügbar; enthält die Größen 16, 32 und 48 Pixel

So konvertieren Sie Bilder

1. 🖼 Bilder optimieren öffnen.
2. Bei Konvertieren nach: das Zielformat wählen — WebP, AVIF oder ICO.
3. Über Suchfeld und Ordnerauswahl eingrenzen, dann die Bilder ankreuzen. Zu jeder Datei werden die Abmessungen angezeigt.
4. Nicht auswählbare Zeilen tragen ihre Begründung: „Erfordert GD oder Imagick mit WebP-Unterstützung, auf diesem Server nicht verfügbar.“, „Bereits eine %s-Datei — bitte ein anderes Zielformat wählen.“ oder „%s existiert bereits — zum erneuten Konvertieren zuerst löschen.“
5. 🖼 Ausgewählte Dateien konvertieren anklicken.
6. Die Bestätigung lautet „%d Datei(en) nach %s konvertiert.“
7. Die neuen Dateien liegen im selben Ordner wie das Original, mit gleichem Namen und neuer Endung. Sie werden dadurch nirgends automatisch eingebunden — passen Sie Inhaltselemente, Templates oder Stylesheets selbst an, wenn das neue Format ausgeliefert werden soll.

Teil 3 — Für Entwickler

Das Paket registriert den Namensraum Vtinnovations\FileInspector\ und bringt sein Contao-Manager-Plugin mit, das das Bundle nach dem ContaoCoreBundle lädt. Eine manuelle Registrierung ist nicht nötig.

Tabellen und Migrationen

Tabelle	Inhalt	Backend-Oberfläche
tl_fi_scan	Kopfdaten je Scan: Modus, Status, Benutzer, Dauer, Kennzahlen, Konfigurations-Snapshot	Keine — kein DataContainer. Die Zeilen werden ausschließlich vom Modul geschrieben und gelesen.
tl_fi_bin	Papierkorb-Einträge: ursprünglicher Pfad, Größe, UUID, frühere Einstufung und der Datensatz-Abzug für die Wiederherstellung	Keine — kein DataContainer.

Beide DCA-Dateien existieren nur, damit Contaos Schema-Aktualisierung die Tabellen nicht für verwaist hält und ein DROP vorschlägt. Die vollständigen Scan-Ergebnisse und die Dateiinhalte des Papierkorbs liegen nicht in der Datenbank, sondern unter var/.

Die mitgelieferten Migrationen laufen über contao:migrate und lassen sich gefahrlos mehrfach ausführen — eine bereits erledigte Migration wird übersprungen:

Migration	Wirkung
„File Inspector: create scan history table (tl_fi_scan)“	Legt die Verlaufstabelle an
„File Inspector: create recycle-bin table (tl_fi_bin)“	Legt die Papierkorb-Tabelle an
„File Inspector: add skipped-source-file stats and metadata_json columns to tl_fi_scan“	Ergänzt Spalten für übersprungene Quelldateien und den Konfigurations-Snapshot

Das Paket bringt darüber hinaus eine interne Migration mit, die keine Aktion erfordert.

Laufzeitverzeichnisse

Sämtliche Laufzeitdaten liegen unterhalb von var/ und damit außerhalb des öffentlichen Webverzeichnisses. Die vollständige Liste steht unter Vor der Installation.

Beim Aufbau mehrerer Knoten hinter einem Load Balancer gilt: Der Papierkorb (var/fi_bin/), die Scan-Ergebnisse (var/fi_scans/), die Jobs (var/fi_scan_jobs/) und das private Lizenzverzeichnis müssen auf gemeinsam genutztem Speicher liegen. Andernfalls sehen die Knoten unterschiedliche Stände, ein begonnener Scan lässt sich auf einem anderen Knoten nicht fortsetzen, und der Papierkorb ist von dort aus leer.

Protokolle

Drei Prüfprotokolle im JSON-Lines-Format, je eine Zeile pro Vorgang, unterhalb von var/log/file_inspector/:

Datei	Inhalt
deletions.log	Löschungen: Beginn des Stapels, jede einzelne Datei mit Ergebnis, Abschluss des Stapels
minify.log	Minifizierung: batch_start, je Datei minified (mit Größe vorher/nachher), skipped oder failed, dann batch_end
image_optimization.log	Bildkonvertierung, analog aufgebaut

Die Protokolle enthalten Vorgang, Ergebnis, Zeitstempel, den Benutzernamen und die betroffenen Pfade. Lässt sich das Protokollverzeichnis nicht anlegen, schlägt das Schreiben still fehl, ohne den jeweiligen Vorgang abzubrechen.

Grenzen und Zeitverhalten

Grenze	Wert	Verhalten beim Überschreiten
Dateien je Lösch-, Export-, Minifizier- oder Konvertierungsvorgang	500	Der Überhang wird übersprungen und gemeldet; bei Export & Löschen wird der Vorgang abgewiesen.
Gespeicherte Belege je Datei	10	Die Oberfläche weist auf die Begrenzung hin.
Quelldateigröße im Deep Scan	5 MiB	Datei wird übersprungen und im Bericht gezählt.
Stapelgröße je Hintergrund-Anfrage	500 Upload-Dateien beziehungsweise 25 Quelldateien	—
Lebensdauer eines Hintergrund-Jobs	2 Stunden	Ältere Jobs werden verworfen.
Sperre gegen parallele Scans	30 Minuten	Danach gilt die Sperre als verwaist und wird gelöst.
Wartender Export-&-Löschen-Vorgang	30 Minuten	„Export nicht gefunden oder abgelaufen.“ — es wird nichts gelöscht.
Aufbewahrte Minifizier-Durchläufe	20	Ältere Sicherungen werden entfernt.
Aufbewahrte Scans	50 (fest), zusätzlich Altersregel	Der jüngste Scan bleibt immer erhalten.

Ein Hintergrund-Scan wird in Stapeln über mehrere Anfragen ausgeführt, damit keine einzelne Anfrage in ein PHP-Zeitlimit läuft. Eine Sperrdatei verhindert, dass zwei Scans gleichzeitig starten. Auf der kostenlosen Stufe entfällt dieser Mechanismus: Der Normal Scan läuft dort in einer einzigen, blockierenden Anfrage — bei sehr großen Beständen ist damit max_execution_time die faktische Grenze.

Sicherheitsverhalten bei Dateioperationen

• Jede schreibende Aktion setzt ein gültiges Contao-Anfrage-Token voraus.
• Jeder übermittelte Pfad wird unmittelbar vor der Operation erneut aufgelöst und muss innerhalb des Upload-Verzeichnisses liegen; Traversierungen und Null-Bytes werden zuvor abgewiesen.
• Symbolische Links werden nie gelöscht, Verzeichnisse nie mitverarbeitet.
• Der Zugriff auf das Modul folgt der regulären Contao-Benutzergruppenverwaltung.

Was das Paket nicht anbietet

Diese Liste erspart die Suche:

• Keine Konsolenbefehle. Das Paket registriert keinen eigenen Befehl; ein Scan lässt sich ausschließlich aus dem Backend starten.
• Keinen Cron-Auftrag. Weder Scan noch Aufbewahrung laufen zeitgesteuert.
• Keine Frontend-Module und keine Inhaltselemente. File Inspector ist ein reines Backend-Werkzeug.
• Keine Contao-Hooks und keine öffentlichen Events, an die sich eigener Code hängen ließe.
• Keine Konfigurationsdatei. Es gibt keine Bundle-Konfiguration unter config/; alles Einstellbare liegt im Backend.
• Keine Rücknahme einer Minifizierung über die Oberfläche — siehe CSS und JS minifizieren.

Anpassbar ist an einer Stelle etwas ohne Programmierung: Die Zuordnung von Datenbanktabellen zu sprechenden Namen im Datei-Nachweis („Seiteninhalt“, „Nachrichtenartikel“, „Kalendertermin“ …) stammt aus der Sprachdatei des Pakets und lässt sich in einer eigenen Sprachdatei um weitere Tabellen ergänzen. Nicht aufgeführte Tabellen erhalten einen automatisch aufbereiteten Namen.

Deployment und Cache

1. Paket über Composer aktualisieren.
2. php bin/console contao:migrate ausführen.
3. php bin/console cache:clear ausführen.
4. Sicherstellen, dass die Verzeichnisse unter var/ beim Deployment nicht geleert oder ersetzt werden — insbesondere nicht var/fi_bin/.
5. Bei mehreren Knoten die gemeinsamen Ablagen prüfen (siehe Laufzeitverzeichnisse).

Fehlerbehebung

Symptom	Ursache und Prüfung
„File Inspector“ erscheint nicht im Backend-Menü	Das Modul ist der Benutzergruppe nicht zugewiesen, oder der Cache ist alt. Unter System → Benutzergruppen freigeben, danach den Cache leeren.
„Dieses Plugin benötigt eine Lizenz. Aktivieren Sie sie unter Contao → Einstellungen → File Inspector Licence management.“	Es ist keine gültige Lizenz aktiv. Weiter unter Lizenz aktivieren. Der Abschnitt heißt in den Einstellungen V-T.ONE Licence management, der Block darin File Inspector.
„Diese Funktion erfordert eine Pro-Lizenz.“	Aufgerufen wurde eine der Pro-Funktionen (Deep Scan, Aufräumen, Ignorierregeln, Minifizieren, Bilder optimieren, Verlauf verwalten). Die Freischaltungstabelle zeigt, was die kostenlose Stufe umfasst.
„Für keine Startseite ist eine Domain konfiguriert, daher kann keine Lizenz aktiviert werden.“	In keiner Startseite ist eine Domain hinterlegt. Unter Seitenstruktur die Startseite bearbeiten und die Domain eintragen, dann erneut aktivieren.
„Die Lizenz ist an keine hier konfigurierte Domain gebunden“	Die eingetragene Domain weicht von der lizenzierten ab. Die Bindung gilt exakt — example.com und www.example.com sind verschieden.
„Dieser Lizenzschlüssel wurde abgelehnt. Bitte Schlüssel und gebundene Domains unter v-t.one prüfen.“	Schlüssel oder Domainbindung passen nicht zu dieser Installation. Beides im Kundenkonto abgleichen.
„Der Lizenzdienst war nicht erreichbar. Die installierte Lizenz bleibt aktiv.“	Die ausgehende HTTPS-Verbindung des Servers kam nicht zustande. Der gespeicherte Stand bleibt unverändert; später erneut versuchen. Firewall und ausgehende Verbindungen prüfen.
„Die Lizenz wurde verifiziert, konnte aber nicht gespeichert werden. Bitte prüfen, ob var/file_inspector/ beschreibbar ist.“	Dem Webserver fehlt der Schreibzugriff auf das private Verzeichnis unterhalb von var/. Rechte korrigieren und erneut aktivieren.
„Aktualisierung erforderlich — ‚Update Licence‘ wählen“	Der gespeicherte Stand ist nicht mehr aktuell. Im Lizenzabschnitt Update Licence anklicken.
Deep Scan lässt sich nicht starten, die Karte zeigt 🔒 Pro	Es ist keine Pro-Lizenz aktiv. Die Statuszeile im Lizenzabschnitt zeigt den tatsächlichen Zustand — etwa „Kostenlose Lizenz aktiv“ oder „Pro-Lizenz abgelaufen — kostenlose Funktionen aktiv“.
Beim Start eines Scans erscheint „Ein Scan läuft bereits“	Ein anderer Job ist noch aktiv oder eine Sperre ist verwaist. Scan fortsetzen wählen — oder Neuen Scan starten. Verwaiste Sperren werden nach 30 Minuten selbst gelöst.
„Der Scan konnte nicht abgeschlossen werden.“ oder „Der Scan ist unerwartet fehlgeschlagen; bitte versuchen Sie es erneut.“	Der Lauf brach ab. Auf der kostenlosen Stufe ist die häufigste Ursache das PHP-Zeitlimit beim synchronen Normal Scan. Serverprotokoll prüfen, Ignorierregeln enger fassen, erneut versuchen.
„Im Upload-Verzeichnis wurden keine Dateien gefunden.“ trotz vorhandener Dateien	Die Ignorierregeln schließen zu viel aus. Unter ⚙ Ignorierregeln die aktiven Einträge prüfen — Wildcards wie * greifen weiter, als sie aussehen.
Eine Datei erscheint als „Keine Referenzen gefunden“, obwohl sie im Frontend sichtbar ist	Erwartbar bei einem Normal Scan, wenn die Referenz nur im Template oder in CSS liegt. Einen Deep Scan ausführen. Bleibt das Ergebnis bestehen, wird die Datei vermutlich dynamisch oder extern geladen — nicht löschen.
„Ungültiges oder abgelaufenes Anfrage-Token. Bitte laden Sie die Seite neu und versuchen Sie es erneut.“	Die Backend-Sitzung ist abgelaufen oder das Formular lag zu lange offen. Seite neu laden und die Aktion wiederholen.
„Zu viele Dateien ausgewählt (%d). Die maximale Stapelgröße beträgt %d.“	Grenze von 500 Dateien je Vorgang. Die Auswahl in mehrere Durchgänge aufteilen.
„ZIP-Export konnte nicht erstellt werden“	Meist fehlt die PHP-Erweiterung zip oder das temporäre Verzeichnis ist nicht beschreibbar beziehungsweise voll.
„Die Export-Sitzung ist abgelaufen oder konnte nicht gefunden werden. Es wurden keine Dateien gelöscht.“	Zwischen Export und Bestätigung lagen mehr als 30 Minuten. Der Vorgang ist folgenlos verfallen — Export & Löschen erneut ausführen.
„%d Datei(en) konnten nicht gelöscht werden.“	Dateisystemrechte oder zwischenzeitlich entfernte Dateien. Einzelheiten stehen in var/log/file_inspector/deletions.log.
„Ergebnisdatei fehlt“ beziehungsweise „Die vollständige Ergebnisdatei für diesen Scan ist nicht mehr auf dem Server vorhanden.“	Die JSON-Datei unter var/fi_scans/ wurde durch die Aufbewahrungsregel oder von Hand entfernt. Die Kennzahlen des Scans bleiben erhalten, die Einzelergebnisse nicht. Neuen Scan ausführen.
Der Verwendungs-Explorer meldet „Noch keine Scan-Daten“	Es liegt kein gespeicherter Scan vor, oder dessen Ergebnisdatei fehlt. Zuerst einen Scan ausführen.
„Diese Datei wurde im letzten Scan nicht gefunden.“	Die Datei kam nach dem Scan hinzu oder wird von einer Ignorierregel erfasst. Neu scannen beziehungsweise die Regeln prüfen.
Ein Bild lässt sich nicht konvertieren: „Erfordert GD oder Imagick mit WebP-Unterstützung, auf diesem Server nicht verfügbar.“	Weder GD noch Imagick können das Zielformat schreiben. Ein anderes Zielformat wählen — ICO steht immer zur Verfügung — oder die PHP-Erweiterung serverseitig nachrüsten.
„%s existiert bereits — zum erneuten Konvertieren zuerst löschen.“	Am Zielpfad liegt bereits eine Datei. Bestehende Zieldatei entfernen, dann erneut konvertieren.
Nach dem Minifizieren ist das Layout oder ein Skript defekt	Es gibt keine Schaltfläche zum Zurücknehmen. Die Sicherung liegt unter var/fi_minify_backups/ und wird über manifest.jsonl dem ursprünglichen Pfad zugeordnet; sie wird von Hand zurückkopiert. Nur die 20 jüngsten Durchläufe bleiben erhalten.
Wiederhergestellte Datei erscheint nicht in der Dateiverwaltung	Die Wiederherstellung meldete einen Konflikt oder einen Fehlschlag („%d Datei(en) konnten nicht wiederhergestellt werden.“). Papierkorb erneut öffnen, den Vorgang wiederholen und die Konfliktauswahl bewusst treffen.

Bekannte Einschränkungen

• „Keine Referenzen gefunden“ ist kein Beweis. Der Status besagt, dass in den durchsuchten Quellen keine Referenz erkannt wurde — nicht, dass keine existiert.
• Zur Laufzeit zusammengesetzte Pfade bleiben unsichtbar. Statische Analyse kann sie grundsätzlich nicht auflösen. Dafür gibt es den Status Unsicher, den allerdings nur der Deep Scan vergibt.
• Externe Nutzung wird nicht erkannt. Was ein CDN, ein Newsletter-Versand oder eine Drittanbieter-App ausliefert, sieht der Scanner nicht.
• Der Normal Scan durchsucht keine Quelldateien. Referenzen, die nur in Templates, Skripten oder Stylesheets stehen, findet erst der Deep Scan.
• Der Deep Scan überspringt Quelldateien ab 5 MiB. Anzahl und Gesamtgröße stehen im Bericht; über die Oberfläche ist der Wert nicht änderbar.
• Ignorierte Ordner und Endungen erscheinen in keinem Ergebnis — auch nicht als „referenziert“. Eine zu weit gefasste Regel versteckt Dateien unbemerkt.
• Datenbank-Textfelder werden für die Unsicherheitsanalyse nicht erneut durchsucht.
• Höchstens zehn Belege je Datei werden gespeichert; die tatsächliche Zahl der Fundstellen kann höher liegen.
• 500 Dateien je Vorgang bei Löschen, Export, Minifizieren und Konvertieren.
• Auf der kostenlosen Stufe läuft der Normal Scan blockierend, ohne Fortschrittsanzeige und ohne Möglichkeit, ihn abzubrechen; sehr große Bestände können in das PHP-Zeitlimit laufen.
• Eine Minifizierung lässt sich nicht über die Oberfläche zurücknehmen, und nur die 20 jüngsten Durchläufe werden gesichert.
• Die Bildkonvertierung bindet nichts automatisch ein. Die neuen Dateien liegen bereit, verwendet werden sie erst nach Ihrer Anpassung.
• Die Aufbewahrung des Verlaufs greift nicht zeitgesteuert, sondern nach einem Scan und beim Speichern der Einstellung.
• Kein Konsolenbefehl, kein Cron, kein Frontend-Anteil.

Deinstallation

1. Papierkorb zuerst prüfen. Alles, was dort liegt, existiert nur noch dort. Benötigte Dateien über ↩ Auswahl wiederherstellen zurückholen, bevor Sie fortfahren.
2. Optional die Lizenz unter Contao → Einstellungen → V-T.ONE Licence management → File Inspector mit Remove Licence entfernen, wenn der Schlüssel auf einer anderen Installation weiterverwendet werden soll.
3. Paket entfernen — im Contao Manager unter Pakete → Installierte Pakete, oder auf der Kommandozeile:

   composer remove vtinnovations/file-inspector

4. Cache leeren:

   php bin/console cache:clear

5. Die Tabellen tl_fi_scan und tl_fi_bin bleiben zunächst bestehen. Contaos Datenbank-Prüfung schlägt danach ihr Entfernen vor; bestätigen Sie das erst, wenn Sie den Verlauf nicht mehr benötigen.
6. Die Laufzeitdaten unterhalb von var/ von Hand entfernen, sofern nicht mehr benötigt: var/fi_scans/, var/fi_scan_jobs/, var/fi_exports/, var/fi_bin/, var/fi_minify_backups/, var/fi_settings.json, var/fi_retention.json, var/fi_minified.json, var/log/file_inspector/ sowie var/file_inspector/.