fprintf()

Einführung

Die Funktion fprintf() schreibt einen formatierten String in einen Stream — eine Datei, php://stdout, php://stderr oder eine beliebige andere offene Stream-Ressource — und füllt dessen Platzhalter aus einer Liste einzelner Argumente. Das f im Namen steht für file: Im Gegensatz zu printf(), das direkt in die Ausgabe schreibt, sendet fprintf() sein Ergebnis an einen Stream deiner Wahl.

Sie ist das stream-schreibende Mitglied der printf-Familie. Im Vergleich zu vfprintf() erledigen beide Funktionen genau dieselbe Aufgabe, erhalten ihre Werte jedoch unterschiedlich: fprintf() nimmt jeden Wert als eigenes Argument entgegen, während vfprintf() ein einzelnes Array entgegennimmt. Greife zu fprintf(), wenn du eine Handvoll einzelner Werte in eine Datei oder Konsole schreiben möchtest.

Dieses Kapitel behandelt die Syntax, die Formatbezeichner, ausführbare Beispiele, den Vergleich mit verwandten Funktionen und häufige Fallstricke.

Syntax

fprintf(resource $stream, string $format, mixed ...$values): int

Die Funktion gibt die Anzahl der geschriebenen Zeichen zurück. Bei modernen PHP-Versionen wirft ein fehlerhafter Aufruf einen Fehler, anstatt false zurückzugeben, sodass der Rückgabewert selten auf Fehler geprüft werden muss.

Formatbezeichner

Der $format-String mischt literalen Text mit Platzhaltern, die mit % beginnen. Die häufigsten Bezeichner sind:

Zwischen dem % und dem Typbuchstaben können Breite, Auffüllung und Präzision angegeben werden — zum Beispiel %05d (eine Ganzzahl auf 5 Stellen mit Nullen auffüllen) oder %.2f (zwei Nachkommastellen). Ein literales % muss als %% geschrieben werden.

Beispiel: Schreiben in die Standardausgabe

Das Öffnen des php://stdout-Streams lässt dich das Ergebnis sofort sehen, was das Ausprobieren von fprintf() erleichtert:

<?php

$out = fopen("php://stdout", "w");

fprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", "John", 30, 1234.5);

fclose($out);

Ausgabe:

Name: John | Age: 30 | Balance: 1234.50

Die drei Argumente füllen %s, %d und %.2f der Reihe nach: Der String wird unverändert ausgegeben, %d schneidet den Dezimalteil einer Ganzzahl ab, und %.2f formatiert die Gleitkommazahl auf genau zwei Nachkommastellen.

Beispiel: Schreiben in eine Datei

Der klassische Anwendungsfall ist das Schreiben formatierter, ausgerichteter Zeilen in eine Datei — zum Beispiel ein kleines Log:

<?php

$log = fopen("app.log", "a");

fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "INFO", "Server started");
fprintf($log, "[%s] %-5s %s\n", "2026-07-02", "ERROR", "Disk full");

fclose($log);

echo file_get_contents("app.log");

Ausgabe:

[2026-07-02] INFO  Server started
[2026-07-02] ERROR Disk full

%-5s richtet den Level linksbündig in einer 5-Zeichen-Spalte aus, sodass die Meldungen unabhängig davon, ob der Level INFO oder ERROR lautet, an derselben Position beginnen. Das Öffnen der Datei mit dem Modus "a" (append) fügt jede Zeile hinzu, ohne das bereits Vorhandene abzuschneiden. Jeder fprintf()-Aufruf schreibt eine Zeile und nimmt seine Werte als separate Argumente entgegen.

fprintf() vs. printf() vs. vfprintf()

Diese drei Funktionen teilen sich exakt dieselben Regeln für den Formatstring und unterscheiden sich nur darin, wohin das Ergebnis geht und wie die Werte übergeben werden:

fprintf() ist also printf(), das in einen Stream statt in die Ausgabe schreibt, und es ist vfprintf() mit separaten Argumenten anstelle eines Arrays:

// Separate Argumente → geschrieben in $stream
fprintf($stream, "%s is %d", $name, $age);

// Dieselben Werte als Array → geschrieben in $stream
vfprintf($stream, "%s is %d", [$name, $age]);

Wenn du nur den formatierten String zurückbekommen möchtest, ohne ihn irgendwohin zu schreiben, verwende sprintf(). Ein gängiges fprintf()-Idiom in Kommandozeilenskripten ist das Schreiben von Diagnosemeldungen in den Fehlerstream, getrennt von der normalen Ausgabe:

<?php

fprintf(STDERR, "Error: %s (code %d)\n", "connection refused", 111);

STDERR ist eine vordefinierte Stream-Konstante, die PHP-CLI-Skripten zur Verfügung steht, sodass du sie nicht erst mit fopen() öffnen musst.

Häufige Fallstricke

• Der Stream kommt zuerst. Die Stream-Ressource ist das erste Argument, der Formatstring das zweite. Den Formatstring zuerst zu übergeben (wie bei printf()) ist der häufigste Fehler beim Wechsel zwischen den beiden Funktionen.
• Der Stream muss beschreibbar sein. Eine Datei mit "r" (Lesemodus) zu öffnen und sie an fprintf() zu übergeben, schlägt fehl — verwende einen beschreibbaren Modus wie "w" (überschreiben) oder "a" (anhängen).
• Die Funktion schreibt, gibt keinen Text zurück. Der Rückgabewert ist die Zeichenanzahl, nicht der formatierte String — eine häufige Verwechslung mit sprintf().
• Zu wenige Argumente lösen einen Fehler aus. Werden weniger Werte übergeben, als der Format-String Bezeichner enthält, wirft PHP 8+ einen ArgumentCountError; überzählige Werte werden einfach ignoriert.
• Literale Prozentzeichen als %% escapen, andernfalls versucht PHP, das nächste Zeichen als Bezeichner zu lesen.

Fazit

fprintf() formatiert einen String und schreibt ihn in einen Stream, wobei die Werte als separate Argumente übergeben werden. Sie ist das Mittel der Wahl, wenn du präzise, spaltenweise Ausgaben in eine Datei oder auf die Konsole schreiben möchtest — Log-Zeilen, Berichte oder CLI-Diagnosemeldungen auf php://stderr. Für die verwandten Varianten siehe printf() (gibt auf der Ausgabe aus), sprintf() (gibt einen String zurück) und vfprintf() (gleiches Ziel, nimmt aber ein Array von Werten entgegen).

Übung