fscanf()

Was ist die Funktion fscanf()?

Die Funktion fscanf() liest aus einer geöffneten Datei und verarbeitet deren Inhalt gemäß einem printf-ähnlichen Formatstring. Anstatt wie fgets() eine rohe Textzeile zurückzugeben, zerlegt fscanf() die Eingabe in einem einzigen Schritt in typisierte Felder — strings, integers, floats. Sie ist PHP's bevorzugtes Werkzeug, wenn eine Datei einem festen, spaltenbasierten Layout folgt und man jeden Wert bereits in den richtigen Typ konvertiert haben möchte.

Diese Seite behandelt die Syntax, die verwendbaren Formatbezeichner, die zwei Möglichkeiten, wie fscanf() seine Ergebnisse zurückgeben kann, die häufigsten Fallstricke und den Vergleich mit verwandten Funktionen.

Syntax

fscanf(resource $stream, string $format, mixed &...$vars): array|int|false

Der Rückgabewert hängt davon ab, wie die Funktion aufgerufen wird:

• Mit zusätzlichen Variablenargumenten → gibt die Anzahl der erfolgreich zugewiesenen Felder zurück, oder false am Dateiende.
• Ohne zusätzliche Variablen → gibt ein array der geparsten Felder zurück, anstatt in Variablen zu schreiben.

fscanf() rückt den Dateizeiger über das Verarbeitete hinaus vor, sodass wiederholte Aufrufe Token für Token durch die Datei wandern.

Formatbezeichner

Der Formatstring ist das Herzstück von fscanf(). Die häufigsten Bezeichner sind:

Leerzeichen im Formatstring passen auf jede Folge von Leerzeichen (Leerzeichen, Tabulatoren, Zeilenumbrüche) in der Eingabe, weshalb %s durch Leerzeichen begrenzt wird und nicht durch Zeilenenden.

Eine Datei mit Variablen lesen

Das typische Muster lautet: Datei öffnen, in einer Schleife iterieren, solange fscanf() die erwartete Feldanzahl zurückgibt, dann schließen. Angenommen, data.txt enthält einen Datensatz pro Zeile:

John Smith 30 50000.5
Jane Doe 28 62000

Jede Zeile kann wie folgt in typisierte Variablen geparst werden:

<?php
$file = fopen('data.txt', 'r');

if ($file === false) {
    die("Error: Could not open file.");
}

while (fscanf($file, "%s %s %d %f", $first, $last, $age, $salary) === 4) {
    echo "Name: $first $last, Age: $age, Salary: $salary\n";
}

fclose($file);
?>

Ausgabe:

Name: John Smith, Age: 30, Salary: 50000.5
Name: Jane Doe, Age: 28, Salary: 62000

Den Rückgabewert mit 4 (der Anzahl der Felder, die das Format erwartet) zu vergleichen, ist der Schlüssel zu einer sicheren Schleife: Am Dateiende gibt fscanf() false zurück, und bei einer fehlerhaften Zeile einen kleineren Zählwert, sodass die Schleife sauber beendet wird, anstatt endlos zu laufen.

Eine Datei in ein Array lesen

Wenn die Variablenargumente weggelassen werden, gibt fscanf() jeden geparsten Datensatz als array zurück. Das ist praktisch, wenn Zeilen gesammelt statt eine Variable nach der anderen verarbeitet werden sollen:

<?php
$file = fopen('data.txt', 'r');

while ($row = fscanf($file, "%s %s %d %f")) {
    // $row is [first, last, age, salary]
    [$first, $last, $age, $salary] = $row;
    echo "$last, $first earns $salary\n";
}

fclose($file);
?>

Ausgabe:

Smith, John earns 50000.5
Doe, Jane earns 62000

fscanf() vs. sscanf()

fscanf() liest von einem Dateizeiger; sscanf() führt genau dasselbe Parsing durch, jedoch auf einem string, der bereits im Speicher vorhanden ist. Wenn die Daten in einer Variablen statt in einer Datei vorliegen, sollte sscanf() verwendet werden:

<?php
$count = sscanf("2024-06-21", "%d-%d-%d", $year, $month, $day);
echo "$count fields parsed: $year / $month / $day\n";
?>

Ausgabe:

3 fields parsed: 2024 / 6 / 21

Häufige Fallstricke

• %s stoppt bei Leerzeichen, nicht am Zeilenende. Ein Name wie New York wird als zwei %s-Felder gelesen, nicht als eines. Die tatsächliche Struktur der Daten muss berücksichtigt werden.
• Den Rückgabewert immer prüfen. Die Schleife am Feldanzahl-Vergleich (=== 4) — nicht an !feof() — zu orientieren, schützt vor unvollständigen Zeilen und Endlosschleifen.
• fopen() zuerst verifizieren. fscanf() benötigt eine gültige Ressource; ein fehlgeschlagenes Öffnen gibt false zurück.
• Für kommagetrennte Daten ist fgetcsv() vorzuziehen. fscanf() ist für leerzeichenbegrenzte Spalten mit festem Format gedacht, nicht für CSV-Felder mit Anführungszeichen.

Verwandte Funktionen

• sscanf() — einen formatierten string anstatt einer Datei parsen.
• fgetcsv() — CSV-Zeilen lesen und aufteilen.
• fgets() — eine rohe Textzeile lesen.
• fopen() / fclose() — den Dateistream öffnen und schließen.

Fazit

fscanf() wandelt leerzeichenbegrenzte Dateiinhalte in einem einzigen Aufruf in typisierte PHP-Werte um. Die Variablenform eignet sich für die Verarbeitung von Datensätzen einzeln nacheinander, die array-Form für das Sammeln mehrerer Datensätze. Der Rückgabewert sollte immer zur Steuerung der Schleife genutzt werden, und für In-Memory-strings sollte auf sscanf() umgestiegen werden bzw. auf fgetcsv() für echte CSV-Daten.

Übung