extended firefly import options, cleaned up language usage in code, new README in english, changed license references
Co-authored-by: Copilot <copilot@github.com>
This commit is contained in:
Reindl David (IT-PTR-CEN2-SL10)
co-authored by
Copilot
Copilot
parent
90dc37cafc
commit
a6ed05a38a
+87
-87
@@ -10,16 +10,16 @@ use UbsCsvTransformer\ColumnTransformer;
|
||||
use UbsCsvTransformer\FireflyImporter;
|
||||
|
||||
/**
|
||||
* Orchestriert die gesamte CSV-Transformations-Pipeline
|
||||
* Orchestrates the complete CSV transformation pipeline
|
||||
*
|
||||
* Koordiniert alle Schritte von CSV-Einlesen über Metadaten-Extraktion
|
||||
* und Spalten-Transformation bis zur Ausgabe und optional zum Import in Firefly III.
|
||||
* Coordinates all steps from reading the CSV through metadata extraction
|
||||
* and column transformation to output and optional import into Firefly III.
|
||||
*
|
||||
* @property ConfigurationLoader $configLoader Verwaltet Konfiguration
|
||||
* @property CsvWriter $csvWriter Schreibt Output-CSV
|
||||
* @property MetadataExtractor $metadataExtractor Extrahiert Metadaten aus Header
|
||||
* @property ColumnTransformer $columnTransformer Transformiert Spalten
|
||||
* @property array $csvStructure CSV-Struktur-Konfiguration
|
||||
* @property ConfigurationLoader $configLoader Manages configuration
|
||||
* @property CsvWriter $csvWriter Writes output CSV
|
||||
* @property MetadataExtractor $metadataExtractor Extracts metadata from header
|
||||
* @property ColumnTransformer $columnTransformer Transforms columns
|
||||
* @property array $csvStructure CSV structure configuration
|
||||
*/
|
||||
class TransformerEngine
|
||||
{
|
||||
@@ -33,16 +33,16 @@ class TransformerEngine
|
||||
private bool $debugMode = false;
|
||||
|
||||
/**
|
||||
* Initialisiert TransformerEngine mit Konfiguration
|
||||
* Initialises TransformerEngine with configuration
|
||||
*
|
||||
* Lädt alle erforderlichen Konfigurationen und initialisiert
|
||||
* die Komponenten (MetadataExtractor, ColumnTransformer, CsvWriter).
|
||||
* CsvReader wird später in transform() und validate() initialisiert mit dem Dateipfad.
|
||||
* Loads all required configurations and initialises
|
||||
* the components (MetadataExtractor, ColumnTransformer, CsvWriter).
|
||||
* CsvReader is instantiated later in transform() and validate() with the file path.
|
||||
*
|
||||
* @param ConfigurationLoader $configLoader Lädt Konfigurationsdateien
|
||||
* @param bool $debugMode true = Debug-Modus aktivieren
|
||||
* @param ConfigurationLoader $configLoader Loads configuration files
|
||||
* @param bool $debugMode true = enable debug mode
|
||||
*
|
||||
* @throws \RuntimeException wenn erforderliche Konfigurationen fehlen
|
||||
* @throws \RuntimeException if required configurations are missing
|
||||
*/
|
||||
public function __construct(ConfigurationLoader $configLoader, bool $debugMode = false)
|
||||
{
|
||||
@@ -63,7 +63,7 @@ class TransformerEngine
|
||||
$config['capitalizationExceptions'] ?? []
|
||||
);
|
||||
|
||||
// Bestimme Output-Dateiname aus Konfiguration
|
||||
// Determine output file name from configuration
|
||||
$outputDir = $config['directories']['output'] ?? './output';
|
||||
$outputFileName = $config['csvStructure']['outputFilename'] ?? 'transformed.csv';
|
||||
$outputFile = rtrim($outputDir, '/') . '/' . $outputFileName;
|
||||
@@ -75,9 +75,9 @@ class TransformerEngine
|
||||
}
|
||||
|
||||
/**
|
||||
* Aktiviert oder deaktiviert den Debug-Modus
|
||||
* Enables or disables debug mode
|
||||
*
|
||||
* @param bool $enabled true = Debug-Modus aktiviert
|
||||
* @param bool $enabled true = debug mode enabled
|
||||
* @return void
|
||||
*/
|
||||
public function setDebugMode(bool $enabled): void
|
||||
@@ -91,30 +91,30 @@ class TransformerEngine
|
||||
}
|
||||
|
||||
/**
|
||||
* Transformiert eine CSV-Datei
|
||||
* Transforms a CSV file
|
||||
*
|
||||
* Führt folgende Schritte durch:
|
||||
* 1. CSV-Datei einlesen mit CsvReader
|
||||
* 2. Metadaten aus Header extrahieren
|
||||
* 3. Spalten gemäß Konfiguration transformieren
|
||||
* 4. Daten in Output-CSV schreiben
|
||||
* 5. Beispiel-Daten sammeln (maximal 3 Zeilen oder maxRows)
|
||||
* Performs the following steps:
|
||||
* 1. Read CSV file with CsvReader
|
||||
* 2. Extract metadata from header
|
||||
* 3. Transform columns according to configuration
|
||||
* 4. Write data to output CSV
|
||||
* 5. Collect sample data (maximum 3 rows or maxRows)
|
||||
*
|
||||
* Der Output-Dateipfad wird aus der Konfiguration bestimmt und kann nicht überschrieben werden.
|
||||
* The output file path is determined from the configuration and cannot be overridden.
|
||||
*
|
||||
* @param string $inputFile Pfad zur Input-CSV-Datei
|
||||
* @param int $maxRows Maximale Anzahl Datenzeilen zu transformieren (0 = alle).
|
||||
* Beispiel-Daten werden begrenzt auf min(3, maxRows)
|
||||
* @param string $inputFile Path to the input CSV file
|
||||
* @param int $maxRows Maximum number of data rows to transform (0 = all).
|
||||
* Sample data is limited to min(3, maxRows)
|
||||
*
|
||||
* @return array Transformations-Ergebnis mit:
|
||||
* - success: bool (true = erfolgreich, false = Fehler)
|
||||
* - inputFile: string (Input-Dateipfad, nur bei Erfolg)
|
||||
* - outputFile: string (Output-Dateipfad, nur bei Erfolg)
|
||||
* - rowsProcessed: int (tatsächlich verarbeitete Datenzeilen)
|
||||
* - sampleData: array (Erste Beispiel-Zeilen, max 3 oder maxRows)
|
||||
* - metadata: array (Extrahierte Metadaten, nur bei Erfolg)
|
||||
* - outputColumns: int (Anzahl Output-Spalten)
|
||||
* - error: string (Fehlermeldung, nur bei Fehler)
|
||||
* @return array Transformation result with:
|
||||
* - success: bool (true = successful, false = error)
|
||||
* - inputFile: string (input file path, on success only)
|
||||
* - outputFile: string (output file path, on success only)
|
||||
* - rowsProcessed: int (actually processed data rows)
|
||||
* - sampleData: array (first sample rows, max 3 or maxRows)
|
||||
* - metadata: array (extracted metadata, on success only)
|
||||
* - outputColumns: int (number of output columns)
|
||||
* - error: string (error message, on failure only)
|
||||
*/
|
||||
public function transform(string $inputFile, int $maxRows = 0): array
|
||||
{
|
||||
@@ -130,50 +130,50 @@ class TransformerEngine
|
||||
]);
|
||||
}
|
||||
|
||||
// Validiere Input-Datei
|
||||
// Validate input file
|
||||
if (!file_exists($inputFile)) {
|
||||
throw new \RuntimeException("Input-Datei nicht gefunden: {$inputFile}");
|
||||
throw new \RuntimeException("Input file not found: {$inputFile}");
|
||||
}
|
||||
|
||||
// Initialisiere CsvReader mit Dateipfad und Konfiguration
|
||||
// Initialise CsvReader with file path and configuration
|
||||
$csvReader = new CsvReader($inputFile, $this->csvStructure);
|
||||
|
||||
// Lese Metadaten-Zeilen (vor der Header-Zeile)
|
||||
// Read metadata lines (before the header line)
|
||||
$metadataLines = $csvReader->readMetadataLines();
|
||||
|
||||
// Extrahiere Metadaten aus den Metadaten-Zeilen
|
||||
// Extract metadata from the metadata lines
|
||||
$metadata = $this->metadataExtractor->extract($metadataLines);
|
||||
|
||||
// Initialisiere ColumnTransformer mit extrahierten Metadaten
|
||||
// Initialise ColumnTransformer with extracted metadata
|
||||
$this->columnTransformer = new ColumnTransformer(
|
||||
$this->configLoader->get('columnTransformations', []),
|
||||
$metadata,
|
||||
$this->configLoader->get('capitalizationExceptions', [])
|
||||
);
|
||||
|
||||
// Lese CSV-Daten mit Header-Keys als Array-Keys
|
||||
// Read CSV data with header keys as array keys
|
||||
$dataRows = $csvReader->readCsvData($maxRows);
|
||||
if (empty($dataRows)) {
|
||||
throw new \RuntimeException("Keine Datenzeilen in CSV-Datei");
|
||||
throw new \RuntimeException("No data rows in CSV file");
|
||||
}
|
||||
|
||||
// Berechne Limit für Beispiel-Daten
|
||||
// Calculate limit for sample data
|
||||
$sampleLimit = $maxRows == 0 ? 3 : $maxRows;
|
||||
|
||||
// Transformiere Zeilen und sammle sie
|
||||
// Transform rows and collect them
|
||||
$transformedData = [];
|
||||
|
||||
foreach ($dataRows as $row) {
|
||||
// Prüfe ob maxRows erreicht
|
||||
// Check if maxRows reached
|
||||
if ($maxRows > 0 && $this->rowsProcessed >= $maxRows) {
|
||||
break;
|
||||
}
|
||||
|
||||
// Transformiere Zeile
|
||||
// Transform row
|
||||
$transformedRow = $this->columnTransformer->transformRow($row);
|
||||
$transformedData[] = $transformedRow;
|
||||
|
||||
// Speichere Beispiel-Daten
|
||||
// Save sample data
|
||||
if (count($this->sampleData) < $sampleLimit) {
|
||||
$this->sampleData[] = $transformedRow;
|
||||
}
|
||||
@@ -181,7 +181,7 @@ class TransformerEngine
|
||||
$this->rowsProcessed++;
|
||||
}
|
||||
|
||||
// Entferne Spalten die aus dem Output ausgeschlossen werden sollen
|
||||
// Remove columns to be excluded from the output
|
||||
$excludeColumns = $this->csvStructure['excludeOutputColumns'] ?? [];
|
||||
if (!empty($excludeColumns)) {
|
||||
$excludeMap = array_flip($excludeColumns);
|
||||
@@ -195,7 +195,7 @@ class TransformerEngine
|
||||
);
|
||||
}
|
||||
|
||||
// Schreibe alle transformierten Daten in Output-CSV
|
||||
// Write all transformed data to output CSV
|
||||
$this->csvWriter->write($transformedData);
|
||||
|
||||
$result = [
|
||||
@@ -225,43 +225,43 @@ class TransformerEngine
|
||||
}
|
||||
|
||||
/**
|
||||
* Transformiert und importiert CSV in Firefly III
|
||||
* Transforms and imports CSV into Firefly III
|
||||
*
|
||||
* Führt Transformation durch und importiert die Ausgabe-Datei
|
||||
* in Firefly III wenn in der Konfiguration aktiviert.
|
||||
* Performs transformation and imports the output file
|
||||
* into Firefly III if enabled in the configuration.
|
||||
*
|
||||
* Rückwärts-kompatibel mit legacy Signatur.
|
||||
* Backwards-compatible with legacy signature.
|
||||
*
|
||||
* @param string $inputFile Pfad zur Input-CSV-Datei
|
||||
* @param int $maxRows Maximale Anzahl Datenzeilen zu verarbeiten (0 = alle)
|
||||
* @param string $inputFile Path to the input CSV file
|
||||
* @param int $maxRows Maximum number of data rows to process (0 = all)
|
||||
*
|
||||
* @return array Transformations- und Import-Ergebnis mit:
|
||||
* - success: bool (true = transformation erfolgreich)
|
||||
* @return array Transformation and import result with:
|
||||
* - success: bool (true = transformation successful)
|
||||
* - inputFile: string
|
||||
* - outputFile: string
|
||||
* - rowsProcessed: int
|
||||
* - sampleData: array
|
||||
* - metadata: array
|
||||
* - outputColumns: int
|
||||
* - import: array (Firefly Import-Ergebnis, wenn autoImport aktiv)
|
||||
* - error: string (falls Fehler)
|
||||
* - import: array (Firefly import result, if autoImport active)
|
||||
* - error: string (if error)
|
||||
*/
|
||||
public function transformAndImport(string $inputFile, int $maxRows = 0): array
|
||||
{
|
||||
// Zuerst transformieren
|
||||
// Transform first
|
||||
$transformResult = $this->transform($inputFile, $maxRows);
|
||||
|
||||
if (!$transformResult['success']) {
|
||||
return $transformResult;
|
||||
}
|
||||
|
||||
// Prüfe ob Auto-Import in Konfiguration aktiviert ist
|
||||
// Check whether auto-import is enabled in configuration
|
||||
$fireflyConfig = $this->configLoader->get('fireflyImport', []);
|
||||
if (empty($fireflyConfig['autoImport'])) {
|
||||
return $transformResult;
|
||||
}
|
||||
|
||||
// Führe Firefly-Import durch
|
||||
// Perform Firefly import
|
||||
try {
|
||||
$importer = new FireflyImporter($fireflyConfig);
|
||||
$importResult = $importer->import($transformResult['outputFile']);
|
||||
@@ -278,19 +278,19 @@ class TransformerEngine
|
||||
}
|
||||
|
||||
/**
|
||||
* Validiert eine CSV-Datei gegen die Konfiguration
|
||||
* Validates a CSV file against the configuration
|
||||
*
|
||||
* Prüft ob erforderliche Metadaten vorhanden sind
|
||||
* und ob die CSV-Struktur der Konfiguration entspricht.
|
||||
* Checks whether required metadata is present
|
||||
* and whether the CSV structure matches the configuration.
|
||||
*
|
||||
* @param string $inputFile Pfad zur zu validierenden CSV-Datei
|
||||
* @param string $inputFile Path to the CSV file to validate
|
||||
*
|
||||
* @return array Validierungs-Ergebnis mit:
|
||||
* - valid: bool (true = Validierung erfolgreich)
|
||||
* - metadata: array (Extrahierte Metadaten, wenn valid)
|
||||
* - line_count: int (Gesamtzahl Zeilen, wenn valid)
|
||||
* - error: string (Fehlermeldung, wenn nicht valid)
|
||||
* - metadata_found: array (Gefundene Metadaten trotz Fehler)
|
||||
* @return array Validation result with:
|
||||
* - valid: bool (true = validation successful)
|
||||
* - metadata: array (extracted metadata, when valid)
|
||||
* - line_count: int (total number of lines, when valid)
|
||||
* - error: string (error message, when not valid)
|
||||
* - metadata_found: array (found metadata despite error)
|
||||
*/
|
||||
public function validate(string $inputFile): array
|
||||
{
|
||||
@@ -298,18 +298,18 @@ class TransformerEngine
|
||||
if (!file_exists($inputFile)) {
|
||||
return [
|
||||
'valid' => false,
|
||||
'error' => "Datei nicht gefunden: {$inputFile}",
|
||||
'error' => "File not found: {$inputFile}",
|
||||
];
|
||||
}
|
||||
|
||||
// Initialisiere CsvReader mit Dateipfad
|
||||
// Initialise CsvReader with file path
|
||||
$csvReader = new CsvReader($inputFile, $this->csvStructure);
|
||||
|
||||
// Extrahiere Metadaten-Zeilen (vor der Header-Zeile)
|
||||
// Extract metadata lines (before the header line)
|
||||
$metadataLines = $csvReader->readMetadataLines();
|
||||
$metadata = $this->metadataExtractor->extract($metadataLines);
|
||||
|
||||
// Prüfe auf erforderliche Metadaten
|
||||
// Check for required metadata
|
||||
$requiredMetadata = [
|
||||
'account_iban',
|
||||
'currency_code',
|
||||
@@ -325,12 +325,12 @@ class TransformerEngine
|
||||
if (!empty($missingMetadata)) {
|
||||
return [
|
||||
'valid' => false,
|
||||
'error' => 'Fehlende Metadaten: ' . implode(', ', $missingMetadata),
|
||||
'error' => 'Missing metadata: ' . implode(', ', $missingMetadata),
|
||||
'metadata_found' => $metadata,
|
||||
];
|
||||
}
|
||||
|
||||
// Zähle Gesamtzahl Zeilen
|
||||
// Count total number of lines
|
||||
$lineCount = $csvReader->countLines();
|
||||
|
||||
return [
|
||||
@@ -341,15 +341,15 @@ class TransformerEngine
|
||||
} catch (\Exception $e) {
|
||||
return [
|
||||
'valid' => false,
|
||||
'error' => 'Validierungs-Fehler: ' . $e->getMessage(),
|
||||
'error' => 'Validation error: ' . $e->getMessage(),
|
||||
];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Gibt die gesammelten Beispiel-Daten zurück
|
||||
* Returns the collected sample data
|
||||
*
|
||||
* @return array Beispiel-Daten (maximal 3 oder maxRows Zeilen)
|
||||
* @return array Sample data (maximum 3 or maxRows rows)
|
||||
*/
|
||||
public function getSampleData(): array
|
||||
{
|
||||
@@ -357,9 +357,9 @@ class TransformerEngine
|
||||
}
|
||||
|
||||
/**
|
||||
* Gibt die Anzahl verarbeiteter Datenzeilen zurück
|
||||
* Returns the number of processed data rows
|
||||
*
|
||||
* @return int Anzahl transformierter Zeilen
|
||||
* @return int Number of transformed rows
|
||||
*/
|
||||
public function getRowsProcessed(): int
|
||||
{
|
||||
|
||||
Reference in New Issue
Block a user