Piwigo_Bratonien_Tools/README.md

Piwigo Bratonien Tools

Modulares Piwigo-Plugin für Administration, Bildverarbeitung, geschützte Freigaben, Fotoauswahl und die Anbindung von Nextcloud an Piwigo.

Aktuelle Plugin-Version: 0.9.6.8.19

Grundprinzip

Bratonien Tools erweitert Piwigo um Funktionen, die in der Bratonien-Installation benötigt werden, hält die einzelnen Module aber möglichst unabhängig voneinander.

Für die Administration gilt: Der normale Nutzer sieht Aufgaben, Entscheidungen und Ergebnisse. Technische Interna werden automatisch ermittelt oder bleiben hinter ausdrücklich technischen Einstellungen verborgen.

NC Connector

Der NC Connector bindet ausdrücklich ausgewählte Nextcloud-Inhalte per WebDAV an Piwigo an. Nextcloud bleibt dabei die Quelle der Originaldateien; Piwigo verwaltet Alben, Bilder und seine eigenen Derivate.

Datenmodell

• Nextcloud bleibt die verbindliche Quelle der Originaldateien.
• Originalbilder werden nicht dauerhaft als zweite vollständige Bibliothek unter Piwigo gespeichert.
• Eine lokale Platzhalterquelle enthält physische 1×1-Dateien, damit Piwigo die Bilder regulär als Dateisysteminhalte erkennen kann.
• Ein Shadow Tree bildet daraus die von Piwigo erwartete Galerie-Ordnerstruktur.
• Ordner werden als physische Piwigo-Alben synchronisiert.
• Direkt im ausgewählten Nextcloud-Root liegende Einzelbilder werden über die vorhandene Orphan-Logik behandelt.
• Neu importierte physische Connector-Alben werden privat angelegt.
• Entfernte Quellen verschwinden aus Shadow Tree und Piwigo; die Nextcloud-Originale bleiben erhalten.

Nextcloud-Root ohne künstliches Benutzeralbum

Ein leerer webdav_path ist ein gültiger Root und bedeutet den Dateibereich des authentifizierten Nextcloud-Benutzers.

Dabei wird der Nextcloud-Benutzername nicht als künstliche Album-Ebene angelegt. Beispiel:

Nextcloud
/
├── 400 Auswahl/
├── Zweites Album/
├── einzelbild-1.jpg
└── einzelbild-2.jpg

wird in Piwigo logisch als

400 Auswahl
Zweites Album

abgebildet. Die direkt im Root liegenden Einzelbilder werden separat durch die Orphan-Synchronisierung erfasst.

Voraussetzungen

Benötigt werden nur:

• Nextcloud-Adresse;
• Nextcloud-Benutzer bzw. App-Passwort;
• normaler WebDAV-Zugriff auf die Inhalte dieses Benutzers;
• eine normale Piwigo-Installation mit ihrer vorhandenen PHP-/Bildverarbeitungsumgebung.

Nicht benötigt werden Nextcloud-Datenbankzugriff, occ-Adminzugriff, Storage-IDs, Backend-Pfade, zusätzliche Host-Mounts, FUSE, davfs oder rclone.

WebDAV-Scan und Shadow Tree

1. Der Assistent prüft Nextcloud und liest die sichtbaren Verzeichnisse per WebDAV.
2. Ausgewählte Verzeichnisse werden rekursiv per PROPFIND eingelesen.
3. Ordner, Dateiname, Nextcloud-Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad werden erfasst.
4. runtime/lib/build_webdav_placeholder_source.py erzeugt eine lokale Platzhalterquelle ohne dauerhafte Originalkopie.
5. runtime/lib/shadow_tree.py baut atomar den verbindungseigenen Shadow Tree.
6. Der WebDAV-Galeriebaum liegt unter _data/bratonien-tools/nc-webdav-gallery/connection-ID.
7. Jede WebDAV-Verbindung wird als eigene physische Piwigo-Site registriert.
8. Piwigos Dateisynchronisierung erhält ausschließlich diese verbindungseigene Site.

On-Demand-Bildauslieferung und Piwigo-Derivate

Die produktive Bildauslieferung sitzt vor Piwigos i.php.

include/webdav_materialize_runtime.inc.php erkennt anhand des Piwigo-Bildpfads die zugehörige WebDAV-Verbindung, den Nextcloud-Root und den relativen WebDAV-Pfad. Der Hook get_derivative_url leitet fehlende WebDAV-Derivate an webdav-derivative.php um.

Wenn ein benötigtes Piwigo-Derivat noch nicht existiert:

1. webdav-derivative.php prüft den Piwigo-Zugriff auf das Bild.
2. Das Original wird temporär direkt aus Nextcloud geladen.
3. Die physische 1×1-Platzhalterdatei bzw. der Shadow-Link am von Piwigo erwarteten Quellpfad wird für die Dauer der Erzeugung ersetzt.
4. Piwigos eigenes i.php erzeugt das normale Piwigo-Derivat.
5. Danach wird der temporäre Originalzustand entfernt und der Platzhalter-/Shadow-Zustand wiederhergestellt.
6. Das von Piwigo erzeugte Derivat wird ausgeliefert und künftig normal aus Piwigos Derivat-Cache verwendet.

Damit bleibt Piwigo für Größen, Derivate und Lazy-Loading verantwortlich. Der Connector hält keinen parallelen eigenen vollständigen Derivat-Cache vor.

Für Fälle, in denen Piwigo direkt die Originalquelle benötigt, steht weiterhin die serverseitige WebDAV-Auslieferung zur Verfügung. Nextcloud-Zugangsdaten werden nicht an den Browser weitergegeben.

Piwigo-Synchronisierung

Der Connector verwendet die vorhandene Piwigo-Dateisynchronisierung für die verbindungseigene WebDAV-Site. Der Shadow Tree ist ausschließlich die Dateisystemdarstellung, die Piwigo für Alben und Bilder benötigt.

runtime/lib/piwigo-sync.php bevorzugt die Webservice-Methode bratonien.nc.syncProductive. Ist keine Piwigo-API für die Verbindung eingerichtet, wird der vorhandene Administrator-/Webmaster-Benutzername/Passwort-Fallback verwendet und Piwigos nativer site_update ausgeführt.

Nach der regulären Dateisynchronisierung läuft bratonien.nc.syncOrphans für direkt im Site-Root liegende Einzelbilder.

Die produktive Synchronisierung ist aktuell auf Piwigo 16.4.0 abgestimmt.

Private Top-Level-Alben

Durch das Überspringen der technischen Nextcloud-Benutzerebene können WebDAV-Unterordner zu echten Top-Level-Piwigo-Alben werden. Für den Connector-Sync wird deshalb der Zugriff des verwendeten Piwigo-Administrators auf neu erzeugte private Top-Level-Alben erhalten und der Benutzer-Cache anschließend invalidiert.

Administrations-Dashboard

Piwigo 16.4.0 blendet seine Album-Statistik standardmäßig bei exakt einem Album aus (NB_ALBUMS > 1). Bratonien Tools passt ausschließlich diese Dashboard-Anzeige auf NB_ALBUMS > 0 an. Dadurch wird auch ein einzelnes korrekt angelegtes Album in der Verwaltungsübersicht angezeigt.

Statusanzeige

Die Administration zeigt Laufzeitstatus und Fehler pro Verbindung. Fehlerdetails bleiben der betroffenen Verbindung zugeordnet.

Löschen einer Verbindung

Beim Löschen einer WebDAV-Verbindung werden ihre zugehörige Piwigo-Site und die dazugehörigen Piwigo-Datensätze entfernt. Nextcloud-Dateien bleiben unverändert. Runtime-, Shadowtree-, Source-, Preview- und Statusdaten werden bereinigt.

Runtime

Aktive WebDAV-Verbindungen werden über den gemeinsamen Runner verarbeitet:

• bratonien-nc-connector.timer
• bratonien-nc-connector.service
• runtime/run-all.sh

Verbindungsspezifische Konfigurationen liegen unter /etc/bratonien-tools/nc-connector/, State-Daten unter /var/lib/bratonien-tools/nc-connector/connection-ID.

Der gemeinsame Lauf besteht aktuell aus:

1. runtime/reconcile-webdav.php – gespeicherte Verbindungen in Runtime-Konfigurationen überführen;
2. runtime/repair-webdav-orphans.php – vorhandene WebDAV-Orphan-Zustände reparieren;
3. runtime/cleanup-webdav-piwigo.php – verwaiste WebDAV-Piwigo-Daten bereinigen;
4. runtime/sync-webdav.sh – jede vorhandene WebDAV-Verbindung synchronisieren.

Der verbindungsspezifische Lauf erzeugt Platzhalterquelle und Shadow Tree, führt Piwigos Sync und Orphan-Sync aus und enthält weiterhin die vorhandenen Preview-/Derivative-Schritte. Die produktive Auslieferung fehlender WebDAV-Derivate erfolgt jedoch über den On-Demand-Gate vor i.php.

Bildcache

Bratonien Tools kann Piwigo-Bildderivate gezielt leeren, vorhandene Bildgrößen neu erzeugen und den Cache-Aufbau als Worker-Prozess starten bzw. abbrechen. Originalbilder bleiben unangetastet.

Wasserzeichenverwaltung

• eigene Wasserzeichendateien;
• Wasserzeichenprofile;
• globale Regeln für öffentliche/private Alben;
• Album-Ausnahmen und Vererbung;
• Position, Transparenz und Skalierung;
• eigener Runtime-Filter für Piwigo-Derivate;
• Sicherung der bisherigen Piwigo-Wasserzeichenkonfiguration beim Aktivieren.

Bilddateien und Pfade

• Upload nach local/bratonien/assets/;
• Vorschau, Abmessungen und Dateigröße;
• Löschen verwalteter Assets;
• konfigurierbare PHP-Uploadgrenzen über .user.ini, sofern die Serverkonfiguration dies zulässt.

Fotoauswahl und Batch Downloader

Bratonien Tools erweitert Albumseiten um eine öffentliche bzw. berechtigungsabhängige Bildauswahl und übergibt nur die ausgewählten Bild-IDs an das Piwigo-Plugin Batch Downloader.

Abhängigkeit: Batch Downloader muss installiert und aktiv sein.

Fortlaufende Bildtitel

Die globale Piwigo-Stapelverarbeitung erhält die Aktion Fortlaufende Bildtitel mit Präfix, Startnummer, Stellenzahl, Sortierung und Schutz vorhandener individueller Titel. Physische Dateinamen werden nicht verändert.

Albumzugriff

Alben können in Bratonien Tools zwischen öffentlich und privat umgeschaltet werden. Beim Sperren wird verhindert, dass sich der handelnde Benutzer versehentlich selbst aussperrt.

Geschützte Albumfreigaben

Private Alben können über eigene Freigabelinks geteilt werden, optional mit Passwort und Ablaufdatum. Die Freigaben verwenden einen technischen Piwigo-Benutzer mit minimalem Albumzugriff und können widerrufen werden.

Erweiterte Bildnavigation

Die Piwigo-Bilddetailseite erhält responsive Navigationszonen für vorheriges Bild, nächstes Bild, Rückkehr zur Übersicht und PhotoSwipe/Vollbild.

Selbstaktualisierung

Der integrierte Updater liest den Zielstand aus GitHub, bindet ein Update an einen konkreten Commit, prüft Version und SHA-256, erstellt vor dem Austausch ein Backup und verlangt Webmaster-Rechte sowie die notwendigen Servervoraussetzungen.

Wichtige Dateien und Verzeichnisse

• main.inc.php – Plugin-Einstieg, Hooks, Connector-Sync-Hilfen und Dashboard-Prefilter
• admin.php – zentraler Admin-Controller
• include/nc_connector.inc.php – WebDAV-Verbindungsmodell
• include/nc_connector_wizard.inc.php – Verbindungsassistent
• include/nc_connector_wizard_webdav_flow.inc.php – WebDAV-Wizardablauf
• include/nc_connector_delete_safe.inc.php – Löschen einschließlich WebDAV-Piwigo-Inhalten
• include/nc_productive_ws.inc.php – direkter Piwigo-Core-Dateisync für Piwigo 16.4.0
• include/nc_orphan_ws.inc.php – Orphan-Synchronisierung der konkreten WebDAV-Site
• include/webdav_materialize_runtime.inc.php – WebDAV-Quellauflösung und On-Demand-Materialisierung
• include/webdav_image_runtime.inc.php – vorhandene WebDAV-Bildzuordnung/Originalauslieferung
• webdav-derivative.php – Gate vor i.php für fehlende WebDAV-Derivate
• webdav-image.php – serverseitige WebDAV-Originalauslieferung
• runtime/reconcile-webdav.php – WebDAV-Runtime-Reconcile, einschließlich gültigem leerem Root
• runtime/repair-webdav-orphans.php – Reparatur vorhandener Orphan-Zustände
• runtime/cleanup-webdav-piwigo.php – Bereinigung verwaister WebDAV-Piwigo-Sites
• runtime/sync-webdav.sh – Ablauf einer WebDAV-Verbindung
• runtime/run-all.sh – gemeinsamer WebDAV-Runner
• runtime/lib/build_webdav_placeholder_source.py – rekursiver WebDAV-Scan und physische Platzhalterquelle
• runtime/lib/shadow_tree.py – atomarer, Piwigo-kompatibler Shadow Tree
• runtime/lib/piwigo-sync.php – Piwigo-Sync mit API/Fallback
• main-cache-build.php – allgemeiner Piwigo-Derivat-/Cache-Builder
• include/self_update.inc.php – Self-Updater
• include/album_shares.inc.php – geschützte Albumfreigaben und private Albumzugriffe
• include/public_selection.inc.php – Fotoauswahl
• include/batch_titles.inc.php – fortlaufende Titel
• include/watermark_*.inc.php – Wasserzeichen-Engine
• tools/ – administrative Einzelwerkzeuge
• template/, js/, css/ – Oberfläche

Sicherheit

• administrative Schreibaktionen verwenden Piwigos CSRF-Schutz;
• Connector-Zugangsdaten werden verschlüsselt gespeichert;
• Nextcloud-Zugangsdaten werden verbindungseigen gespeichert und nur serverseitig verwendet;
• Wizard-Geheimnisse werden nicht im Browser-Web-Storage persistiert;
• produktive Piwigo-API ist versionsgebunden;
• Originalbilder werden vom Connector nicht gelöscht;
• WebDAV-Originalbilder werden nur bei Bedarf temporär lokal materialisiert;
• temporäre Originale werden nach der Piwigo-Derivaterzeugung wieder entfernt;
• Update-Pakete werden an Commit und Hash gebunden.