Plugins verwalten

Plugins verwalten

Vollständige Anleitung zum Installiert-Tab — Anzeigen, Filtern, Aktualisieren, Aktivieren/Deaktivieren, Deinstallieren, Upload-Erkennung, ZIP-Export und alle möglichen Fehler.

Installierte Plugins Liste

Zwei Quellen:

1. Browser-installiert — Vollständiges Tracking (Anbieter, Version, Plugin-ID, Download-URL, Update-Erkennung)
2. Manuell hochgeladen — Vom Scanner automatisch erkannt, als „Manual / Upload" mit eingeschränktem Tracking registriert

Spalten

Upload-Erkennung

scanAndRegisterUploadedPlugins() läuft automatisch:

• Vergleicht JAR-Dateien auf der Festplatte (/plugins/) mit Datenbankeinträgen
• Neue Dateien: Werden mit Anbieter 'upload' registriert. Öffnet JAR zum Extrahieren von plugin.yml für den Namen, oder parst Version aus Dateiname-Regex -(\d+\.\d+(?:\.\d+)?)
• Gelöschte Dateien: Werden aus der Datenbank entfernt (Aufräumen)
• Parallelitätsschutz: Atomare Sperre mit 10-Sekunden-TTL
• Einschränkung: Upload-Plugins haben keine automatische Update-Erkennung

Anzeigename-Auflösung

Filtern

Plugins mit Updates werden nach oben sortiert, dann alphabetisch.

Filter-Beibehaltung

Das Plugin nutzt resetTableKeepingFilters() — speichert den Filterzustand bevor Filament zurücksetzt, stellt ihn danach wieder her. Dies verhindert den Verlust des „has_updates"-Filters beim Navigieren.

Plugins aktualisieren

Wie die Update-Erkennung funktioniert

• Plugin fragt die Quellplattform nach gespeicherter plugin_id und Anbieter ab
• Update-Metadaten 24 Stunden gecacht pro Plugin
• 'upload' Anbieter wird immer übersprungen
• Zeichenkettenvergleich für Versions-IDs (kein Semantic Versioning)

Spezial: Update bei deaktiviertem Plugin

Wenn ein Plugin deaktiviert ist (hat -bak Suffix) wenn ein Update installiert wird:

• Der is_disabled Status wird vor dem Update gemerkt
• Nach dem Update wird das Plugin automatisch erneut deaktiviert
• Dein Deaktiviert-Status bleibt über Updates erhalten

Konsolen-Widget

• Synchronisiert Plugins beim Laden
• Update-Prüfung mit 15-Minuten-Cache
• Warnungs-Badge + Weiterleitungs-URL zum Plugin Browser
• Gleiches Muster wie Game Mods Widget

Plugins aktivieren / deaktivieren

Mechanismus

Datei-Umbenennung über Lesen+Schreiben+Löschen (für Daemon-API-Kompatibilität):

Hinweis: Drei Daemon-API-Aufrufe pro Umschaltung. Der Server muss möglicherweise vorher gestoppt werden.

Benachrichtigungen

Plugins deinstallieren

Prozess

1. Klicke Deinstallieren → Warnung bestätigen
2. JAR-Datei wird aus /plugins/ gelöscht
3. Datenbankeintrag wird entfernt
4. Benachrichtigung: „Plugin uninstalled"
5. Server neustarten um vollständig zu entladen

Was NICHT entfernt wird

Plugins-Ordner öffnen

Springt zu /plugins/ im Dateimanager. Nützlich für:

• Tatsächliche Dateien auf der Festplatte prüfen
• Manuelle Uploads
• Aufräumen von Konfigurationsverzeichnissen nach der Deinstallation
• Überprüfen von -bak Erweiterungen bei deaktivierten Plugins

ZIP-Export

Prozess

1. Klicke Alle als ZIP herunterladen
2. Benachrichtigung: „ZIP download started"
3. Server komprimiert alle Dateien in /plugins/
4. JWT-signierte URL wird generiert (läuft nach 30 Minuten ab)
5. Download startet automatisch

Enthält: Alle Plugins (aktive + deaktivierte)

Vollständige Fehlerreferenz

„Failed to read installed plugins"

• /plugins/-Verzeichnis existiert nicht → Server einmal starten
• Verzeichnis nicht lesbar → Daemon-Berechtigungen prüfen
• Festplatte voll
• Daemon-Verbindung verloren

„Failed to disable/enable plugin"

• Berechtigungen: Lesen + Schreiben + Löschen erforderlich auf /plugins/
• Datei gesperrt: Laufender Server sperrt Dateien → Server zuerst stoppen
• Gleichzeitiger Zugriff: Backup oder Dateimanager greift gleichzeitig zu
• Datei nicht gefunden: Extern umbenannt oder gelöscht
• Daemon-Fehler: Jeder der 3 Schritte (Lesen/Schreiben/Löschen) kann fehlschlagen

„Failed to delete old versions"

• Alte Datei vom laufenden Server gesperrt → Server stoppen
• Dateiberechtigungsproblem
• Datei bereits manuell entfernt

Updates werden nicht angezeigt

• Update-Metadaten 24 Stunden gecacht → Cache leeren
• 'upload' Plugins werden immer übersprungen
• Versionsvergleich ist zeichenkettenbasiert
• Anbieter hat Update möglicherweise noch nicht propagiert

„Uninstall failed"

• Datei bereits manuell gelöscht
• Datei vom Serverprozess gesperrt → Stoppen und erneut versuchen
• Daemon-Verbindungsproblem

Plugin lässt Server nach Installation abstürzen

1. Konsolenausgabe / Crash-Report prüfen
2. Plugin deaktivieren (nicht löschen!) + neustarten zur Bestätigung
3. Sind alle Abhängigkeiten installiert?
4. Plugin-Kompatibilität mit MC-Version/Server-Software prüfen
5. Eine ältere stabile Version versuchen
6. Java-Version prüfen (17 für MC 1.18+, 21 für MC 1.21+)

„Cache clear failed"

• Fehlerbenachrichtigung zeigt $e->getMessage()
• SafeCacheService flush() konnte Schlüssel nicht entfernen
• storage/framework/cache/ muss existieren und beschreibbar sein (0755)

„Cache health check failed"

• Warnung vom PluginManager geloggt
• Cache-Infrastruktur muss möglicherweise repariert werden
• php artisan cache:clear als vollständiger Reset

Interne Provider-Funktionen (Referenz)

Dieser Abschnitt dokumentiert den internen PHP-Code für jede Provider-Integration, einschließlich API-Parameter, Antwort-Schemata, Rate-Limits und Verarbeitungslogik.

SpigotMC / Spiget Provider — Vollständige Referenz

API-Endpunkt-Parameter — GET /v2/search/resources/{query}

API-Endpunkt-Parameter — GET /v2/resources (Durchsuchen ohne Query)

Antwort-Schema — Suchergebnisse

Rate-Limits

// SpigotMC-Ressourcen durchsuchen — mit Gesamtanzahl aus Header
$response = Http::timeout($timeout)
    ->get("https://api.spiget.org/v2/search/resources/{$query}", [
        'size' => $perPage,
        'page' => $page,
        'sort' => '-downloads',
    ]);

// Gesamtanzahl steht im X-Total-Antwort-Header (nicht im JSON-Body!)
$total = (int) $response->header('X-Total');

// Antwortverarbeitung — wie Ressourcen in Plugin-Karten umgewandelt werden
$resources = $response->json();
$plugins = collect($resources)->map(function ($r) {
    return [
        'id'            => $r['id'],
        'name'          => $r['name'],
        'summary'       => $r['tag'] ?? '',
        'author'        => '', // Spiget braucht separaten /resources/{id}/author-Aufruf
        'downloads'     => $r['downloads'] ?? 0,
        'icon_url'      => !empty($r['icon']['url'])
            ? "https://www.spigotmc.org/{$r['icon']['url']}"
            : null,
        'updated_at'    => date('c', $r['updateDate'] ?? 0),
        'versions'      => $r['testedVersions'] ?? [],
        'provider'      => 'spiget',
        'has_direct_download' => !($r['premium'] ?? false) && !($r['external'] ?? false),
    ];
});

// Download-Verfügbarkeitsprüfung — HEAD-Anfrage vor dem Download-Versuch
$check = Http::head("https://api.spiget.org/v2/resources/{$id}/download");
if ($check->status() !== 200) {
    // Content-Type-Prüfung: JAR = direkter Download, HTML = Premium/extern
    $contentType = $check->header('Content-Type');
    if (str_contains($contentType, 'text/html')) {
        $plugin['has_direct_download'] = false;
        // Zeigt „Externe Ressource"- oder „Premium"-Badge
    }
}

// Versionsliste abrufen mit Sortierung nach Veröffentlichungsdatum
$versions = Http::timeout($timeout)
    ->get("https://api.spiget.org/v2/resources/{$id}/versions", [
        'size' => 20,
        'sort' => '-releaseDate',
    ])->json();

// Jede Version: { id, uuid, name, releaseDate, downloads, rating }
// Kein Datei-Hash über die Spiget-API verfügbar

Spiget-spezifisches Verhalten:

• Ressourcen mit premium: true können nicht via API heruntergeladen werden — erfordert SpigotMC-Kauf
• Externe Ressourcen (external: true) liegen außerhalb von SpigotMC — Link manuell folgen
• Icons verwenden data/resource_icons/{id}/{id}.jpg-Format vom Spiget-CDN
• Versionsfilterung prüft ob testedVersions die gewünschte MC-Version enthält
• Keine Abhängigkeitsauflösung — die Spiget-API liefert keine Abhängigkeitsdaten
• Autoreninfo benötigt separaten GET /resources/{id}/author-Aufruf — Plugin führt dies verzögert aus

CurseForge Provider (Plugins) — Vollständige Referenz

Verwendet die gleiche CurseForge-API wie Game Mods, aber mit classId=5 (Bukkit Plugins). Die classId ist der entscheidende Unterschied.

API-Endpunkt-Parameter — GET /v1/mods/search

Antwort-Schema — Gleiche Struktur wie Game Mods CurseForge (siehe Game Mods-Dokumentation), wesentliche Unterschiede:

• classId = 5 in allen Ergebnissen
• categories[].classId entspricht Plugin-Kategorien, nicht Mod-Kategorien
• latestFilesIndexes[] kann Bukkit/Spigot/Paper-Kompatibilitätsmarkierungen enthalten

// Plugin-Suche — classId=5 ist der entscheidende Unterschied zu Mods (9137)
$response = Http::withHeaders(['x-api-key' => $apiKey])
    ->timeout($timeout)
    ->get('https://api.curseforge.com/v1/mods/search', [
        'gameId'        => 432,     // Minecraft
        'classId'       => 5,       // ⚠ Bukkit Plugins — NICHT 9137 (Mods)!
        'searchFilter'  => $query,
        'sortField'     => $query ? 1 : 2,  // Dynamische Sortierung
        'sortOrder'     => 'desc',
        'gameVersion'   => $mcVersion,
        'pageSize'      => $perPage,
        'index'         => ($page - 1) * $perPage,
    ]);

// Antwortverarbeitung — gleiche Struktur wie Mods, classId unterscheidet sich
$results = $response->json('data', []);
$plugins = collect($results)->map(function ($mod) {
    return [
        'id'         => $mod['id'],
        'name'       => $mod['name'],
        'slug'       => $mod['slug'],
        'summary'    => $mod['summary'],
        'author'     => $mod['authors'][0]['name'] ?? 'Unbekannt',
        'downloads'  => $mod['downloadCount'],
        'icon_url'   => $mod['logo']['url'] ?? null,
        'provider'   => 'curseforge',
    ];
});

// Rekursive Abhängigkeitsauflösung — gleiches Muster wie bei Game Mods
foreach ($file['dependencies'] as $dep) {
    if ($dep['relationType'] === 3) {  // Benötigte Abhängigkeit
        $depPlugin = $this->fetchMod($dep['modId']);
        $this->installPlugin($depPlugin);  // Rekursiv
    }
}

// Beschreibungsanreicherung — CurseForge kann leere Zusammenfassung liefern
if (empty($mod['summary'])) {
    $html = Http::withHeaders(['x-api-key' => $apiKey])
        ->get("https://api.curseforge.com/v1/mods/{$mod['id']}/description")
        ->body();
    // HTML wird zu Klartext umgewandelt, max 200 Zeichen
}

CurseForge Plugin Provider-Fehlertabelle

Modrinth Provider (Plugins) — Vollständige Referenz

API-Endpunkt-Parameter — GET /v2/search

Plugin-spezifische Facetten

// Das Plugin baut diese Facetten speziell für Server-Plugins
$facets = [
    ['project_type:plugin'],                         // Muss Plugin sein, nicht Mod
    ['categories:paper', 'categories:spigot',        // Serversoftware-Kompatibilität
     'categories:bukkit', 'categories:purpur'],       // ODER-verknüpft im inneren Array
];
if ($mcVersion) $facets[] = ["versions:$mcVersion"];
if ($loader)    $facets[] = ["categories:$loader"];  // z.B. categories:paper

$params['facets'] = json_encode($facets);

Antwort-Schema — Gleiche Struktur wie Game Mods Modrinth (siehe Game Mods-Dokumentation), wesentliche Unterschiede:

• hits[].project_type = "plugin" (nicht "mod")
• hits[].categories enthält Servertypen wie bukkit, spigot, paper, purpur
• hits[].loaders listet unterstützte Serverplattformen

// Antwortverarbeitung — identisch zu Mods, project_type unterscheidet sich
$hits = $response->json('hits', []);
$plugins = collect($hits)->map(function ($hit) {
    return [
        'id'         => $hit['project_id'],
        'name'       => $hit['title'],
        'slug'       => $hit['slug'],
        'summary'    => $hit['description'],
        'author'     => $hit['author'],
        'downloads'  => $hit['downloads'],
        'icon_url'   => $hit['icon_url'] ?? null,
        'versions'   => $hit['versions'] ?? [],
        'provider'   => 'modrinth',
    ];
});

Modrinth Plugin Provider-Fehlertabelle

PaperMC / Hangar Provider — Vollständige Referenz

API-Endpunkt-Parameter — GET /v1/projects

API-Endpunkt-Parameter — GET /v1/projects/{slug}/versions

Antwort-Schema — Projektsuche

Antwort-Schema — Versionen

// Projektsuche — mit Paginierung
$response = Http::timeout($timeout)
    ->get('https://hangar.papermc.io/api/v1/projects', [
        'q'      => $query,
        'limit'  => $perPage,
        'offset' => ($page - 1) * $perPage,
    ]);

// Antwortverarbeitung
$results = $response->json('result', []);
$plugins = collect($results)->map(function ($project) {
    return [
        'id'         => $project['namespace']['slug'],  // owner/slug nicht nötig für Hangar
        'name'       => $project['name'],
        'summary'    => $project['description'],
        'author'     => $project['namespace']['owner'],
        'downloads'  => $project['stats']['downloads'] ?? 0,
        'icon_url'   => $project['avatarUrl'] ?? null,
        'updated_at' => $project['lastUpdated'],
        'provider'   => 'hangar',
    ];
});

// Versionsliste mit Plattform-Priorität
$versions = Http::timeout($timeout)
    ->get("https://hangar.papermc.io/api/v1/projects/{$slug}/versions", [
        'limit' => 20,
    ])->json('result', []);

// Plattform-Priorität: PAPER → VELOCITY → WATERFALL
// Jede Version hat platformDependencies mit MC-Versionsbereichen
foreach ($versions as $v) {
    $mcVersions = $v['platformDependencies']['PAPER'] ?? [];
    // Gibt z.B. ["1.8-1.21"] zurück — bedeutet 1.8 bis 1.21 unterstützt

    // Prüfung auf externe URL — manche Plugins verlinken zu GitHub/Jenkins
    if (!empty($v['downloads']['PAPER'][0]['externalUrl'])) {
        $plugin['requires_manual_download'] = true;
    }
}

Hangar-spezifisches Verhalten:

• Version-agnostisch: Filtert NICHT nach spezifischer MC-Version — zeigt alle Versionen für alle Plattformen
• Projekte verwenden namespace.owner/namespace.slug-Format (z.B. ViaVersion/ViaVersion)
• externalUrl in Downloads → Plugin wird als requires_manual_download markiert
• Statistiken umfassen downloads, stars, watchers — für Sortierungsranking verwendet
• Plugin-Abhängigkeiten in pluginDependencies.PAPER[].name — nur informativ (nicht automatisch aufgelöst)
• MC-Versionsfilter ist in der UI ausgeblendet für Hangar, da serverseitige Filterung nicht unterstützt wird

Hangar Provider-Fehlertabelle

GeyserMC Provider — Vollständige Referenz

API-Endpunkt-Parameter — GET /v2/projects

API-Endpunkt-Parameter — GET /v2/projects/{project}/versions/latest/builds/latest

Die 6 GeyserMC-Projekte

Antwort-Schema — Neuestes Build

// Alle GeyserMC-Projekte auflisten (gibt immer die gleichen 6 zurück)
$projects = Http::timeout($timeout)
    ->get('https://download.geysermc.org/v2/projects')
    ->json();
// ["geyser","floodgate","hurricane","geyserconnect","thirdpartycosmetics","emoteoffhand"]

// Neuestes Build mit plattformspezifischen Downloads abrufen
$build = Http::timeout($timeout)
    ->get("https://download.geysermc.org/v2/projects/{$project}/versions/latest/builds/latest")
    ->json();

// Antwortverarbeitung — Versions-ID wird aus Version + Build zusammengesetzt
$versionId = $build['version'] . '-' . $build['build'];  // z.B. "2.4.0-670"

// Download-Key-Auflösung — Plattform hängt vom Projekt ab
$downloadKey = match ($project) {
    'geyserconnect' => 'standalone',
    default         => 'spigot',  // Paper/Spigot-Server verwenden 'spigot'-Key
};

$jarName  = $build['downloads'][$downloadKey]['name'];      // "Geyser-Spigot.jar"
$sha256   = $build['downloads'][$downloadKey]['sha256'];     // Integritäts-Hash
$url      = "https://download.geysermc.org/v2/projects/{$project}/versions/{$build['version']}/builds/{$build['build']}/downloads/{$downloadKey}";

// GeyserMC spezieller Download — umgeht pull(), nutzt cURL direkt
// Dies liegt daran, dass GeyserMC-URLs spezielle User-Agent-Behandlung erfordern
$tmpFile = tempnam(sys_get_temp_dir(), 'geyser_');
$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => false,
    CURLOPT_FILE           => fopen($tmpFile, 'w'),
    CURLOPT_TIMEOUT        => 60,
    CURLOPT_FOLLOWLOCATION => true,
]);
curl_exec($ch);
curl_close($ch);
// Datei wird dann via Daemon putContent() geschrieben
$this->fileRepository->putContent("/plugins/{$jarName}", file_get_contents($tmpFile));
unlink($tmpFile);

GeyserMC-spezifisches Verhalten:

• Keine Suche — zeigt immer alle 6 Projekte in einer festen Liste
• Version-agnostisch — zeigt immer das neueste Build, keine MC-Versionsfilterung
• SHA-256-Prüfsummen für jeden Download verfügbar — zur Integritätsprüfung verwendet
• Download-URLs: https://download.geysermc.org/v2/projects/{project}/versions/{ver}/builds/{build}/downloads/{platform}
• Verfügbare Plattformen variieren je Projekt: spigot, bungee, standalone, velocity, fabric
• 24-Stunden-Metadaten-Cache für Build-Informationen
• Verwendet Base64-SVG-Insel-Icon für alle Projekte (fest kodiert, nicht aus der API)
• Fest kodierte Download-Zahlen angezeigt (nicht live abgefragt)
• MC-Versionsfilter ist in der UI ausgeblendet für GeyserMC (irrelevant)

GeyserMC Provider-Fehlertabelle

Such-Wiederholungslogik

Wenn die initiale Suche mit Versionsfilter 0 Ergebnisse liefert, wiederholt das Plugin automatisch ohne Versionsfilter. Dies hilft wenn eine bestimmte MC-Version noch nicht beim Provider indiziert ist.

// Automatische Fallback-Suche — gilt für alle durchsuchbaren Provider
$results = $this->search($query, $mcVersion, $loader);
if (empty($results) && $mcVersion) {
    // Wiederholung ohne Versionsfilter — Version evtl. noch nicht indiziert
    $results = $this->search($query, null, $loader);
    // Benutzer sieht alle Versionen, kann Kompatibilität manuell prüfen
}

Providerübergreifende Muster

// Deaktivieren/Aktivieren — in -bak-Namen schreiben, dann Original löschen (Daemon-Kompatibilität)
// Nutzt 3 Schritte: Lesen → neuen Namen schreiben → alten löschen
// KEIN einfaches Umbenennen — Pterodactyl-Daemon unterstützt kein atomares Rename
$content = $this->fileRepository->getContent("/plugins/{$filename}");
$this->fileRepository->putContent("/plugins/{$filename}-bak", $content);
$this->fileRepository->delete("/plugins/{$filename}");

// Update-bei-Deaktivierung — merkt sich deaktivierten Zustand über Updates hinweg
$wasDisabled = $plugin->is_disabled;
$this->updatePlugin($plugin);  // Installiert neue Version
if ($wasDisabled) {
    $this->disablePlugin($plugin);  // Nach Update erneut deaktivieren
}

Vollständige Benachrichtigungs-Referenz

HTTP-Fehlercode-Referenz (Alle Provider)

Provider-spezifische Fehlertabelle

SpigotMC / Spiget Fehler

Hangar Fehler

GeyserMC Fehler