Signatur
Beschreibung
fscanf() liest eine Zeile aus dem Datei-Handle $handle und zerlegt sie anhand des Formatstrings $format in einzelne Werte – analog zur C-Funktion fscanf. Der Formatstring verwendet dieselbe Syntax wie sscanf() bzw. printf() (z. B. %d für Integer, %s für String, %f für Float).
Werden keine optionalen Referenz-Variablen ($vars) übergeben, gibt die Funktion ein Array mit den geparsten Werten zurück. Werden dagegen Variablen als Referenz übergeben, werden die Werte direkt in diese Variablen geschrieben und die Funktion gibt die Anzahl der zugewiesenen Werte zurück.
fscanf() eignet sich besonders zum zeilenweisen Einlesen strukturierter Textdateien, deren Felder durch feste Trennzeichen oder Zeichenbreiten getrennt sind – z. B. Konfigurationsdateien, Log-Dateien oder einfache CSV-ähnliche Formate. Im Gegensatz zu fgets() + sscanf() geschieht das Lesen und Parsen in einem einzigen Aufruf.
Zu beachten ist, dass fscanf() immer genau eine Zeile pro Aufruf konsumiert, auch wenn der Formatstring weniger Felder erwartet als in der Zeile vorhanden sind. Whitespace im Formatstring entspricht einem oder mehreren Whitespace-Zeichen in der Eingabe.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $handle Pflicht | resource | Ein gültiges Datei-Handle, das zuvor mit fopen() oder einer ähnlichen Funktion geöffnet wurde. |
|
| $format Pflicht | string | Formatstring im printf/sscanf-Stil. Unterstützte Konversionszeichen: %d (Integer), %f (Float), %s (String bis Whitespace), %c (einzelnes Zeichen), %o (Oktal), %x (Hex), %n (bisher gelesene Zeichen), %% (literales Prozentzeichen). |
|
| $vars | mixed | Optionale Variablen, die per Referenz übergeben werden. Sind diese angegeben, werden die geparsten Werte direkt in sie geschrieben; die Funktion gibt dann die Anzahl zugewiesener Werte zurück statt eines Arrays. |
Rückgabewert
- Ohne
$vars: Array mit den geparsten Werten (ein Element pro Formatbezeichner). - Mit
$vars: Anzahl der erfolgreich zugewiesenen Werte alsint. nullbei EOF (Ende der Datei).falsebei einem Fehler.
Beispiele
Strukturierte Textdatei zeilenweise einlesen (ohne Referenz-Variablen)
<?php
// Datei users.txt mit Inhalt:
// 1 Alice 28
// 2 Bob 34
$handle = fopen('users.txt', 'r');
if ($handle === false) {
die('Datei konnte nicht geöffnet werden.');
}
while (($data = fscanf($handle, "%d %s %d")) !== null) {
if ($data !== false) {
[$id, $name, $age] = $data;
echo "ID: $id, Name: $name, Alter: $age\n";
}
}
fclose($handle);Werte direkt in Referenz-Variablen schreiben
<?php
// Datei product.txt mit Inhalt:
// 42 19.99 Widget
$handle = fopen('product.txt', 'r');
if ($handle === false) {
die('Datei konnte nicht geöffnet werden.');
}
$count = fscanf($handle, "%d %f %s", $productId, $price, $name);
echo "Zugewiesene Felder: $count\n";
echo "Produkt #$productId: $name kostet " . number_format($price, 2, ',', '.') . " EUR\n";
fclose($handle);EOF und Fehlerbehandlung explizit prüfen
<?php
// Datei log.txt mit Inhalt:
// 2024-01-15 ERROR Verbindungsfehler
// 2024-01-16 INFO Dienst gestartet
$handle = fopen('log.txt', 'r');
if ($handle === false) {
die('Datei nicht lesbar.');
}
while (true) {
$result = fscanf($handle, "%s %s %[^\n]", $date, $level, $message);
if ($result === null) {
echo "Ende der Datei erreicht.\n";
break;
}
if ($result === false) {
echo "Lesefehler aufgetreten.\n";
break;
}
echo "[$date] $level: $message\n";
}
fclose($handle);// Wichtig · Fallstricke
Zeilenweise Verarbeitung: fscanf() liest stets eine vollständige Zeile aus der Datei, auch wenn der Formatstring nicht alle Felder der Zeile abdeckt. Überschüssige Zeileninhalte werden stillschweigend verworfen.
Whitespace-Behandlung: Whitespace im Formatstring (Leerzeichen, Tabs, Zeilenumbrüche) konsumiert eine beliebige Anzahl von Whitespace-Zeichen in der Eingabe. Dies kann zu unerwartetem Verhalten führen, wenn Felder durch genau ein Leerzeichen getrennt sind und mehrere aufeinanderfolgende Leerzeichen in der Eingabe vorkommen.
Alternative: Für CSV-Dateien ist fgetcsv() besser geeignet. Für komplexere Muster empfiehlt sich fgets() in Kombination mit regulären Ausdrücken (preg_match()).
Rückgabewert null vs. false: null zeigt das reguläre Dateiende (EOF) an, false einen Fehler. Diese Unterscheidung ist wichtig für korrekte Schleifen-Abbruchbedingungen.