Importer

Knoten-basierter Importer für Cranach-XML Dateien mit flexiblen Ausgabemöglichkeiten (momentan erstmal JSONs).

Vorbereitung

Da dieses Projekt auf Composer für das Package-Management setzt, muss dies im ersten Schritt global installiert werden. Dazu sei auf die Installationsanweisungen von Composer verwiesen. Unter MacOS kann für eine schnelle Installation auch brew install composer genutzt werden, sofern brew installiert ist.

Ist composer installiert, sollten im nächsten Schritt die Abhängigkeiten installiert werden:

composer install

Aktuell setzt der Importer PHP in Version 8.2 voraus.

Scripts

Um die Nutzung des Importers (aber auch die Entwicklung) zu vereinfachen, kommt das Projekt mit einige Composer-Scripts:

Name	Beschreibung
`lint`	Auflistung von Dateien mit Linter-Problemen
`lint:fix`	Auflistung von Dateien mit Linter-Problemen und automatische Behebung, sofern möglich
`analyse`	Analyse der im `src`-Ordner zu findenden PHP-Dateien; der Analyse-Cache wird über folgenden Befehl geleert: `composer run-script analyse -- --clear-cache`
`clear:cache`	Lösche den Cache-Ordner
`import`	Starten des Import-Vorgangs. Als gelöscht markierte Artefakte werden übersprungen; alternativ `php index.php -x` ausführen
`import:keep-deleted`	Starten des Import-Vorgangs. Als gelöscht markierte Artefakte bleiben erhalten; alternativ `php index.php` ausführen

Import Parameters

Das Import-Script unterstützt die Durchgabe einiger weiterer Parameter.

Parametername	Beschreibung
`keep-soft-deleted-artefacts`	Alle Artefakte behalten, die als 'Soft-Deleted' markiert sind
`refresh-remote-all-cache`	Den kompletten Remote Cache (Bild- und Dokument-Daten) gezielt auffrischen; aktuell unterstützte Werte: `all`, `paintings`, `graphics` und `archivals`; ist kein Wert gegeben, wird standardmäßig auf `all` zurückgefallen
`refresh-remote-images-cache`	Den Remote-Image Cache gezielt auffrischen; aktuell unterstützte Werte: `all`, `paintings`, `graphics` und `archivals`; ist kein Wert gegeben, wird standardmäßig auf `all` zurückgefallen
`refresh-remote-documents-cache`	Den Remote-Document Cache gezielt auffrischen; unterstützte Werte: `all`, `paintings`, `graphics` und `archivals`; ist kein Wert gegeben, wird standardmäßig auf `all` zurückgefallen
`refresh-all-remote-caches`	Alle Remote Caches auffrischen
`use-export`	Spezifischen Export als Basis für den Import verwenden; z. B. `composer run-script import -- --use-export=20230301`

Auf Aufruf mit einem der Paramter würde wie folgt aussehen:

composer run-script import -- --refresh-remote-images-cache=archivals --refresh-remote-documents-cache=archivals

Getting started

Umgebungsvariablen

Für den Importvorgang müssen bestimmte Umgebungsvariablen gesetzt sein. Darunter u.a. ein Access-Key für die entfernt liegenden Bildinformationen. Der Importer geht davon aus, dass im Wurzelverzeichnis eine .env-Datei existiert, die als Basis für die Durchreichung von u.a. sensiblen Daten dient. Die .env sollte am besten von der existierenden .env.example abgeleitet und anschließend angepasst werden:

cp .env.example .env

Importierung

Um neue XML-Dateien importieren zu können, sollten diese im input-Ordner unter einem eigenen Ordner nach dem Muster yyyymmdd abgelegt werden
composer run-script import ausführen
Sofern im vorherigen Punkt der User darauf hingewiesen wird, dass bestimmte Dateien keiner Artefaktgruppe oder für eine Artefaktgruppe keine Datei gefunden werden konnten, müssen die betroffenen XML-Dateien evtl. umbenannt werden.

In-/ und Output Verzeichnisse

Die Input und Output Verzeichnisse sind jetzt nicht mehr Teil des Repos. Daten bitte hierher beziehen, bzw. ablegen:

Input ~/sciebo/cranach/exporte
Output ~/sciebo/cranach/json-output

Bereitgestellte Daten werden bei Bedarf über den Zweig legacy-exchange bereit gestellt.

Entwicklung

Generell sollte immer der über Composer eingebundene Linter und Code-Analyser genutzt werden, um frühzeitig mögliche Formatierungs- und Code-Probleme erkennen und beheben zu können.

Als Linter wird PHP-CS-Fixer mit den in der .php_cs.distangegebenen Rules genutzt.
Als Analyser kommt hingegen Psalm zum Einsatz (in ErrorLevel 3. Siehe psalm.xml.

lucascranach / importer

readme