Laravel-CSV-Import: So planst du einen prüfbaren Workflow

Bei internen CSV-Importen entscheidet nicht allein das Dateiformat über den Erfolg. Sobald eine Fachabteilung Preise, Kundendaten oder Bestände übernimmt, braucht sie einen nachvollziehbaren Ablauf: Daten werden geprüft, Fehler erklärt, Änderungen freigegeben und Wiederholungen sicher behandelt.

Die zentrale Planungsfrage lautet deshalb: Wie gestaltest du den Import so, dass ein Mitarbeiter vor dem Speichern versteht, was passieren wird? Laravel liefert die technischen Bausteine. Der verlässliche Workflow entsteht erst durch klare Entscheidungen rund um Vorschau, Fehlerbehandlung und Freigabe.

Lege zuerst fest, welche Entscheidung der Import vorbereitet

Beginne nicht mit dem Dateiupload, sondern mit dem gewünschten Ergebnis. Ein Import kann neue Datensätze anlegen, vorhandene Daten aktualisieren oder beides erlauben. Diese drei Varianten sehen in einer Schleife ähnlich aus, haben fachlich aber deutlich unterschiedliche Folgen.

Ein Beispiel ist die Preisliste eines Lieferanten. Jede Zeile enthält eine Artikelnummer, einen Nettopreis und einen Lieferstatus. Vor der Umsetzung müssen mindestens diese Fragen beantwortet sein:

• Dürfen unbekannte Artikel automatisch angelegt werden?
• Woran wird ein vorhandener Artikel eindeutig erkannt?
• Was bedeutet ein leeres Feld: Wert löschen, Wert behalten oder Fehler melden?
• Darf ein Preis sinken und steigen, ohne dass jemand die Änderung einzeln prüft?
• Soll eine fehlerhafte Zeile den gesamten Import stoppen?

Diese Regeln gehören in das Briefing und später in automatisierte Tests. Werden sie erst während der Entwicklung geklärt, entscheidet häufig der Quellcode stillschweigend über den Geschäftsprozess. Das ist effizient, bis jemand fragt, warum ein leeres Feld plötzlich einen gültigen Wert entfernt hat.

Definiere einen verbindlichen Importvertrag

Der Importvertrag beschreibt das erwartete Dateiformat und die Bedeutung jeder Spalte. Er sollte für Entwickler und Fachabteilung gleichermaßen verständlich sein. Eine Beispieldatei allein reicht dafür selten aus, weil sie Sonderfälle nicht erklärt.

Für jede Spalte solltest du dokumentieren:

• den exakten Spaltennamen,
• ob der Wert erforderlich oder optional ist,
• welche Formate und Werte zulässig sind,
• wie leere Zellen behandelt werden,
• ob der Wert einen Datensatz identifiziert,
• ob vorhandene Werte überschrieben werden dürfen.

Auch technische Eigenschaften der Datei gehören dazu: Zeichencodierung, Trennzeichen, Datumsformat und Dezimaltrennzeichen. Gerade Tabellenprogramme können dieselbe sichtbare Tabelle unterschiedlich exportieren. Der Import sollte diese Varianten entweder bewusst unterstützen oder mit einer konkreten Meldung ablehnen.

Bei regelmäßig wiederkehrenden Importen ist eine herunterladbare Vorlage sinnvoll. Wechseln die Quelldateien häufig, kann eine Zuordnung der hochgeladenen Spalten zu den Zielfeldern helfen. Diese Zuordnung erhöht allerdings den Bedien- und Testaufwand. Für eine feste Lieferantendatei ist ein festes Schema oft die robustere Wahl.

Trenne Prüfung und Speicherung

Ein sicherer Import besteht aus mindestens zwei fachlichen Phasen. In der Prüfphase liest Laravel die Datei ein, normalisiert die Werte und validiert jede Zeile. Die eigentliche Datenbankänderung folgt erst nach einer bewussten Bestätigung.

Die Vorschau muss keine vollständige Tabelle mit sämtlichen Datensätzen zeigen. Sie sollte die Folgen des Imports zusammenfassen:

• Welche Datensätze werden neu angelegt?
• Welche vorhandenen Datensätze werden geändert?
• Welche Zeilen werden unverändert übersprungen?
• Welche Zeilen enthalten Fehler?
• Welche auffälligen Änderungen erfordern Aufmerksamkeit?

Damit die angezeigte Vorschau zur späteren Ausführung passt, darf Laravel die Datei bei der Freigabe nicht unter veränderten Voraussetzungen blind erneut interpretieren. Du kannst die normalisierten Importzeilen vorübergehend als Importlauf speichern und genau diesen geprüften Stand freigeben. Alternativ muss die Anwendung erkennen, wenn sich Datei oder relevante Ausgangsdaten zwischen Prüfung und Ausführung geändert haben.

Die Validierung des HTTP-Requests deckt dabei nur den äußeren Rahmen ab, etwa ob eine Datei vorhanden ist und eine zulässige Größe hat. Die fachliche Prüfung der enthaltenen Datensätze bleibt eine eigene Aufgabe. Für die saubere Abgrenzung der Request-Validierung hilft der Artikel Laravel Form Request oder Controller-Validierung?.

Formuliere Fehler für die Person vor dem Bildschirm

Eine Meldung wie „Import fehlgeschlagen“ spart Entwicklungszeit und verbraucht sie anschließend im Support. Die Fachabteilung benötigt eine Fehlermeldung, mit der sie die Quelldatei korrigieren kann.

Eine brauchbare Rückmeldung nennt mindestens die Zeile, das betroffene Feld, den gelesenen Wert und die erwartete Regel. Zum Beispiel: „Zeile 18, Feld Nettopreis: Der Wert 12,5 EUR ist nicht zulässig. Erwartet wird eine Zahl ohne Währungsangabe.“

Trenne dabei blockierende Fehler von Warnungen. Eine fehlende Artikelnummer verhindert die eindeutige Zuordnung und muss den Datensatz blockieren. Eine ungewöhnlich starke Preisänderung kann je nach Geschäftsregel als Warnung erscheinen und eine zusätzliche Bestätigung verlangen. Ob eine Auffälligkeit ein Fehler oder eine Warnung ist, entscheidet der Fachprozess, nicht die technische Bequemlichkeit.

Bei umfangreichen Dateien sollte die Fehlerliste herunterladbar sein. Eine ergänzte CSV-Datei mit Zeilennummer und Fehlertext lässt sich meist leichter bearbeiten als eine lange Liste im Browser. Achte beim Export darauf, Werte so zu behandeln, dass Tabellenprogramme enthaltene Formeln nicht ungeprüft ausführen.

Entscheide bewusst zwischen vollständigem und teilweisem Import

Es gibt keine allgemein richtige Regel dafür, ob gültige Zeilen trotz anderer Fehler gespeichert werden dürfen. Die Entscheidung hängt davon ab, ob die Datei eine fachliche Einheit darstellt.

Vollständiger Import

Beim Alles-oder-nichts-Verfahren wird keine Zeile übernommen, solange mindestens ein blockierender Fehler vorliegt. Das passt zu Preisständen, Abrechnungsperioden oder zusammengehörenden Konfigurationen. Die Fachabteilung weiß anschließend eindeutig, dass entweder der komplette Stand aktiv ist oder gar keiner.

Teilweiser Import

Beim teilweisen Import werden gültige Zeilen gespeichert und fehlerhafte Zeilen zurückgewiesen. Das kann bei unabhängigen Kontakten oder einzelnen Produktdatensätzen sinnvoll sein. Dafür muss der Importlauf präzise ausweisen, welche Zeilen übernommen wurden. Ein erneuter Upload der korrigierten Datei darf die bereits verarbeiteten Datensätze nicht unkontrolliert duplizieren.

Die Oberfläche sollte die gewählte Strategie vor der Freigabe deutlich nennen. Eine technisch korrekte Teilverarbeitung wirkt sonst aus Sicht der Fachabteilung wie ein zufälliger halber Erfolg.

Plane Wiederholungen und Duplikate als normalen Fall

Importe werden erneut gestartet: weil der Browser geschlossen wurde, eine Rückmeldung unklar blieb oder eine korrigierte Datei denselben Datenstand enthält. Der Workflow muss deshalb wiederholbar sein, ohne ungewollte Duplikate zu erzeugen.

Grundlage ist ein stabiler fachlicher Schlüssel. Bei Artikeln kann das eine Artikelnummer sein, bei Rechnungen eine Kombination aus Mandant und Rechnungsnummer. E-Mail-Adressen eignen sich nur dann als Schlüssel, wenn der konkrete Geschäftsprozess ihre Eindeutigkeit tatsächlich garantiert.

Lege für Treffer fest, ob Laravel den Datensatz aktualisiert, überspringt oder als Konflikt meldet. Verlasse dich nicht allein auf eine vorherige Abfrage im Anwendungscode. Eindeutige Datenbank-Constraints bilden eine zusätzliche Sicherung, falls zwei Prozesse denselben Datensatz nahezu gleichzeitig anlegen. Wenn du dafür bestehende Tabellen ändern musst, hilft dir der Artikel Laravel-Datenbankmigrationen sicher testen und deployen.

Ein Datei-Hash kann zusätzlich erkennen, dass exakt dieselbe Datei erneut hochgeladen wurde. Er ersetzt den fachlichen Schlüssel jedoch nicht: Eine neue Datei kann dieselben Datensätze enthalten, und eine korrigierte Datei kann erneut verarbeitet werden müssen.

Nutze einen eigenen Status für jeden Importlauf

Ein Importlauf braucht eine Identität und einen nachvollziehbaren Status. Geeignete Zustände sind beispielsweise hochgeladen, wird geprüft, bereit zur Freigabe, freigegeben, wird verarbeitet, abgeschlossen und fehlgeschlagen. Die konkreten Bezeichnungen dürfen einfacher sein; entscheidend ist, dass die Anwendung keine widersprüchlichen Aktionen erlaubt.

Zu einem Importlauf gehören mindestens der Benutzer, der Zeitpunkt, der ursprüngliche Dateiname, die gewählte Importart und eine Zusammenfassung des Ergebnisses. Ob du die Originaldatei aufbewahren darfst und wie lange, hängt von ihrem Inhalt sowie deinen Datenschutz- und Aufbewahrungsregeln ab. Eine unbegrenzte Ablage „für alle Fälle“ ist keine belastbare Regel.

Kleine, berechenbare Dateien können innerhalb einer normalen Anfrage verarbeitet werden. Bei längeren Importen ist ein Laravel-Queue-Job meist besser für die technische Ausführung geeignet. Die Oberfläche muss dann anzeigen, dass der Auftrag angenommen wurde, und den späteren Status abrufen können. Schlägt die Hintergrundverarbeitung fehl, hilft ein gespeicherter Importlauf bei der Zuordnung; für die technische Analyse kannst du den Ablauf aus Laravel Queue-Job schlägt fehl verwenden.

Lege vorab fest, wie Korrekturen funktionieren

Ein pauschaler Rückgängig-Button ist bei Importen schwieriger, als er aussieht. Wenn nach dem Import jemand einen Datensatz manuell bearbeitet hat, kann eine spätere Rücknahme diese Änderung überschreiben. Auch neu angelegte Datensätze können inzwischen von anderen Daten abhängen.

Definiere deshalb passend zum Anwendungsfall eine Korrekturstrategie:

• Eine korrigierte Datei aktualisiert dieselben Datensätze erneut.
• Der Import speichert vorherige Werte und bietet eine kontrollierte Wiederherstellung an.
• Änderungen bleiben bis zu einer zweiten fachlichen Freigabe in einem Zwischenstand.
• Bei sensiblen Vorgängen wird ein Gegenlauf erzeugt, statt historische Änderungen zu löschen.

Für einfache Stammdaten ist der erneute Import mit stabilen Schlüsseln oft ausreichend. Bei Abrechnungen oder rechtlich relevanten Daten sollte die Korrektur selbst als nachvollziehbarer Vorgang behandelt werden.

Formuliere den Workflow als abnehmbare Anforderungen

Für ein Angebot oder internes Ticket sollte der Auftrag nicht „CSV-Import bauen“ lauten. Daraus lassen sich weder Aufwand noch Abnahme zuverlässig ableiten. Eine belastbare Beschreibung enthält konkrete beobachtbare Anforderungen:

1. Der Benutzer kann eine Vorlage mit den erwarteten Spalten herunterladen.
2. Die Anwendung prüft Dateiformat, Spalten und fachliche Werte, ohne dabei Geschäftsdaten zu ändern.
3. Die Vorschau unterscheidet neue, geänderte, unveränderte und fehlerhafte Zeilen.
4. Fehler nennen Zeile, Feld und Korrekturmöglichkeit.
5. Vor der Ausführung ist eine ausdrückliche Freigabe erforderlich.
6. Die Regeln für Duplikate, leere Felder und unbekannte Datensätze sind festgelegt.
7. Nach der Verarbeitung bleibt ein Importprotokoll mit Ergebnis und Verantwortlichem erhalten.
8. Für Fehlschläge und Korrekturen existiert ein definierter Folgeprozess.

Diese Anforderungen machen aus einer technischen Funktion einen prüfbaren Arbeitsablauf. Sie helfen der Agentur bei der Aufwandsschätzung und der Fachabteilung bei der Abnahme, weil beide Seiten über sichtbares Verhalten statt über eine vage Upload-Funktion sprechen.

Fazit: Der Import endet nicht beim erfolgreichen Parsen

Ein Laravel-CSV-Import ist verlässlich, wenn die Fachabteilung seine Folgen vor dem Speichern prüfen und Fehler selbstständig korrigieren kann. Dafür brauchst du einen klaren Importvertrag, eine getrennte Prüf- und Freigabephase, verständliche Rückmeldungen sowie feste Regeln für Teilimporte, Wiederholungen und Korrekturen.

Laravel kann Dateien lesen, Daten validieren, Jobs ausführen und Transaktionen absichern. Ob daraus ein brauchbarer Unternehmensworkflow wird, entscheidet sich jedoch früher: bei der eindeutigen Beschreibung dessen, was mit jeder Zeile passieren darf.

Häufige Fragen

Kurz beantwortet, damit du schneller einschätzen kannst, was für dein Projekt wichtig ist.

Sollte ein Laravel-CSV-Import sofort Daten speichern?

Bei geschäftlich relevanten Daten sollte zuerst eine Prüfphase mit Vorschau erfolgen. Gespeichert wird erst, nachdem blockierende Fehler behoben und die erkannten Änderungen ausdrücklich freigegeben wurden.

Wie verhindert Laravel doppelte Datensätze beim CSV-Import?

Verwende einen stabilen fachlichen Schlüssel, definiere das Verhalten bei vorhandenen Datensätzen und sichere echte Eindeutigkeit zusätzlich durch einen Datenbank-Constraint ab. Ein Datei-Hash allein reicht dafür nicht.

Muss ein CSV-Import über eine Laravel Queue laufen?

Nein. Kleine und berechenbare Importe können synchron verarbeitet werden. Für längere Vorgänge ist ein Queue-Job sinnvoll, sofern die Oberfläche Status, Abschluss und Fehlschläge verständlich anzeigt.

Sollten gültige Zeilen trotz Fehlern importiert werden?

Das hängt vom Fachprozess ab. Zusammengehörende Datenstände sprechen für ein Alles-oder-nichts-Verfahren. Bei unabhängigen Datensätzen kann ein Teilimport sinnvoll sein, wenn übernommene und abgelehnte Zeilen eindeutig protokolliert werden.