Die Bedeutung der package.xml im WoltLab Suite Core
Die Datei package.xml ist das Herzstück und die Steuerzentrale jedes WoltLab-Pakets (Plugins oder Designs). Sie enthält alle Metadaten wie den Paketnamen, den Entwickler, Versionen, Abhängigkeiten zu anderen Plugins sowie die Anweisungen (Pipelines), welche Dateien wohin installiert werden müssen. Ohne diese Datei weiß das WoltLab-Installationssystem nicht, was es mit dem Archiv tun soll.
Das "First-File"-Problem im Tar- oder Zip-Archiv
Eine Besonderheit des WoltLab-Paketmanagers ist die strikte Anforderung an die interne Struktur des Archivs. Die package.xml darf nicht irgendwo liegen – sie muss sich zwingend im Hauptverzeichnis (Root) des Archivs befinden und idealerweise an erster Stelle im Index des Archivs stehen.
Wird das Paket hochgeladen und der Paketmanager findet die Datei nicht sofort beim Öffnen des Archivs, bricht der Prozess mit einer Fehlermeldung wie "Das gewählte Archiv ist kein gültiges Paket" ab.
📂 So muss die korrekte Archiv-Struktur aussehen:
mein_plugin.tar (oder .zip) ├── package.xml <-- MUSS direkt hier liegen! ├── files.tar <-- Optional (enthält PHP/JS-Dateien) ├── templates.tar <-- Optional (enthält HTML-Templates) └── acpTemplates.tar <-- Optional (enthält ACP-Templates)
Häufige Ursachen für Installationsfehler
- Falsch verpackt (Unterordner-Problem): Der häufigste Fehler passiert beim Packen des Archivs. Wenn du den gesamten Ordner
"mein_plugin"rechtsklickst und komprimierst, legt das Packprogramm einen Unterordner im Archiv an. Die Struktur ist dann:mein_plugin.tar/mein_plugin/package.xml. Das System sucht aber auf der obersten Ebene und scheitert. - Fehlerhafter XML-Inhalt: Selbst wenn die Datei an erster Stelle liegt, bricht die Installation ab, wenn die XML-Syntax fehlerhaft ist (z. B. nicht geschlossene Tags) oder ungültige Zeichen verwendet wurden.
- Falscher Zeichensatz: Die
package.xmlsollte immer in UTF-8 (ohne BOM) abgespeichert sein, um Codierungskonflikte während des Einlesens zu vermeiden.
🛠️ Anleitung: Richtig packen für WoltLab
Um das "Unterordner-Problem" und die falsche Reihenfolge zu vermeiden, gehe wie folgt vor:
- Öffne den Ordner, in dem deine Plugin-Dateien liegen (du musst die Dateien direkt sehen, nicht den übergeordneten Ordner).
- Markiere alle Dateien gemeinsam (STRG + A / CMD + A), wobei du darauf achtest, dass die
package.xmlmit ausgewählt ist. - Nutze ein Packprogramm (wie 7-Zip oder WinRAR) und erstelle das Archiv (vorzugsweise als
.tar). - Tipp für macOS-Nutzer: macOS legt versteckte Systemdateien (wie
.DS_Store) an. Diese können die Reihenfolge im Archiv stören. Nutze am besten ein Terminal oder spezielle Tools wie den WoltLab Package Builder, um saubere Archive zu erstellen.