fprint()

Die PHP-Funktion fprintf() schreibt einen formatierten string in eine geöffnete Datei (Stream). Man kann sie sich wie printf() vorstellen — das in den Browser/die Ausgabe schreibt —, nur dass das Ziel auf ein Datei-Handle umgeleitet wird. Sie ist die naheliegende Wahl, wenn man sauberen, ausgerichteten und vorhersehbaren Text in einer Logdatei oder einem generierten Bericht möchte, anstatt Strings mühsam per Verkettung zusammenzubauen.

Diese Seite behandelt die Syntax, die am häufigsten verwendeten Format-Spezifizierer, zwei vollständige ausführbare Beispiele sowie eng verwandte Funktionen, die alternativ eingesetzt werden können.

Syntax

int fprintf ( resource $handle , string $format [, mixed ...$args ] )

Die Funktion gibt die Anzahl der geschriebenen Bytes zurück oder false bei einem Fehler. Beachten Sie, dass der Rückgabewert die Länge des geschriebenen Strings ist, nicht die Anzahl der Argumente — nützlich, wenn Sie verfolgen möchten, wie viele Daten protokolliert wurden.

Format-Spezifizierer

Die Stärke von fprintf() liegt im $format-string. Jedes % leitet einen Platzhalter ein:

Dieselben Spezifizierer funktionieren in printf() und sprintf(), sodass das hier Gelernte überall anwendbar ist.

Einen Bericht schreiben

Hier ist ein vollständiges Beispiel, das einen kleinen Bericht in eine Datei schreibt.

<?php
$file = fopen("report.txt", "w");
if ($file === false) {
    die("Failed to open file");
}
$name = "John";
$age = 30;
$income = 50000;
// \$ prints a literal dollar sign; %.2f rounds the float to 2 decimals
$bytes = fprintf($file, "Name: %s\nAge: %d\nIncome: \$%.2f", $name, $age, $income / 12);
fclose($file);

echo "$bytes bytes written"; // 35 bytes written
?>

Wir öffnen report.txt zum Schreiben ("w") und prüfen, dass fopen() nicht fehlgeschlagen ist. fprintf() ersetzt dann jede Variable im Format-string: %s für den Namen, %d für das Alter und \$%.2f für das monatliche Einkommen (ein wörtliches $ gefolgt von einem auf zwei Dezimalstellen gerundeten Float). Rufen Sie immer fclose() auf, wenn Sie fertig sind, damit der Puffer geleert und das Handle freigegeben wird.

Die resultierende report.txt enthält:

Name: John
Age: 30
Income: $4166.67

50000 / 12 ergibt 4166.6667, was %.2f auf 4166.67 rundet.

An eine Logdatei anhängen

Ein sehr häufiger Anwendungsfall ist das Anhängen einer formatierten Zeile an ein Log. Öffnen Sie die Datei im Anhängemodus ("a"), sodass jeder Aufruf eine neue Zeile hinzufügt, anstatt den vorherigen Inhalt zu überschreiben:

<?php
$file = fopen("error.log", "a");
if ($file === false) {
    die("Failed to open file");
}
$error_code = 404;
$date = date("Y-m-d H:i:s");
$ip_address = $_SERVER['REMOTE_ADDR'];
fprintf($file, "[%s] Error %d from IP address %s\n", $date, $error_code, $ip_address);
fclose($file);
?>

Da die Datei mit "a" geöffnet wird, fügt jeder Durchlauf eine neue Zeile hinzu; nichts, was bereits in error.log steht, geht verloren. Das \n am Ende des Format-Strings platziert jeden Eintrag in einer eigenen Zeile. Eine typisch angehängte Zeile sieht so aus:

[2023-03-15 15:30:00] Error 404 from IP address 192.168.0.1

fprintf() vs. verwandte Funktionen

Die richtige Wahl hält Ihren Code übersichtlich:

• printf() — gleiche Formatierung, schreibt aber in die Standardausgabe (Browser/CLI) statt in eine Datei.
• sprintf() — gibt den formatierten string zurück, anstatt ihn irgendwo zu schreiben, sodass Sie ihn speichern oder wiederverwenden können.
• fwrite() — schreibt rohe Bytes in eine Datei ohne Formatierung; verwenden Sie es, wenn Sie keine %-Platzhalter benötigen.
• vfprintf() — wie fprintf(), nimmt die Argumente jedoch als einzelnes array statt als variablen Liste entgegen.

Häufige Fallstricke

• Nicht übereinstimmende Spezifizierer und Argumente. %d auf einen nicht-numerischen string ergibt 0; weniger Argumente als Platzhalter anzugeben löst eine Warnung aus.
• Vergessen, % zu escapen. Um ein wörtliches Prozentzeichen auszugeben, verwenden Sie %%, nicht %.
• fclose() vergessen. Gepufferte Daten werden möglicherweise erst auf den Datenträger geschrieben, wenn das Handle geschlossen wird (oder das Skript endet).
• Der Öffnungsmodus ist entscheidend. "w" kürzt die Datei ab; "a" hängt an. Wählen Sie bewusst.

Übung