vfprintf()

Einführung

Die Funktion vfprintf() schreibt einen formatierten String in einen Stream — zum Beispiel eine Datei oder die Standardausgabe — und entnimmt die Werte dabei aus einem Array anstatt aus einer Liste einzelner Argumente. Das vorangestellte v steht für vector (ein Array von Argumenten); das f steht für file (sie schreibt in einen Stream).

Kurz gesagt verhält sich vfprintf() zu fprintf() wie vsprintf() zu sprintf(): Die Formatierung ist dieselbe, aber es wird ein einziges Array übergeben, anstatt jeden Wert einzeln anzugeben. Diese Funktion wird verwendet, wenn die Werte bereits in einem Array zusammengefasst sind.

Dieses Kapitel behandelt die Syntax, die Formatbezeichner, ausführbare Beispiele, wann man sie gegenüber Alternativen bevorzugt und häufige Fallstricke.

Syntax

vfprintf(resource $stream, string $format, array $values): int

Die Funktion gibt die Anzahl der geschriebenen Zeichen zurück. Bei den meisten PHP-Versionen wirft ein fehlerhafter Aufruf einen Fehler, anstatt false zurückzugeben, sodass der Rückgabewert normalerweise nicht 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

Die Verwendung des php://stdout-Streams ermöglicht es, das Ergebnis sofort zu sehen, was das Ausprobieren von vfprintf() erleichtert:

<?php

$out    = fopen("php://stdout", "w");
$values = ["John", 30, 1234.5];

vfprintf($out, "Name: %s | Age: %d | Balance: %.2f\n", $values);

fclose($out);

Ausgabe:

Name: John | Age: 30 | Balance: 1234.50

Die drei Array-Elemente 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 ursprüngliche Anwendungsfall ist das Schreiben formatierter Zeilen in eine Datei. Hier werden drei Zeilen aus einem Array von Datensätzen angehängt:

<?php

$records = [
    ["Alice", 95],
    ["Bob",   82],
    ["Carol", 77],
];

$file = fopen("scores.txt", "w");

foreach ($records as $row) {
    vfprintf($file, "%-10s %3d%%\n", $row);
}

fclose($file);

echo file_get_contents("scores.txt");

Ausgabe:

Alice       95%
Bob         82%
Carol       77%

%-10s richtet den Namen linksbündig in einer 10-Zeichen-Spalte aus, %3d richtet die Punktzahl rechtsbündig in einer 3-Zeichen-Spalte aus, und %% gibt das literale Prozentzeichen aus. Da jedes $row bereits ein Array ist, verarbeitet vfprintf() es direkt — die Werte müssen nicht entpackt werden.

Warum ein Array verwenden? vfprintf() vs. fprintf()

fprintf() nimmt die Werte als separate Argumente entgegen:

fprintf($file, "%s is %d", $name, $age);

vfprintf() nimmt dieselben Werte in einem einzigen Array entgegen:

vfprintf($file, "%s is %d", [$name, $age]);

vfprintf() eignet sich, wenn die Werte bereits in einem Array vorliegen — beispielsweise eine Datenbankzeile, eine geparste CSV-Zeile oder Argumente, die in einer Schleife aufgebaut werden — sodass sie nicht mit dem Spread-Operator (...$row) entpackt werden müssen. Wenn stattdessen der formatierte String zurückgegeben werden soll, anstatt ihn in einen Stream zu schreiben, wird vsprintf() verwendet; um direkt in die Ausgabe zu schreiben ohne eine Stream-Ressource, wird vprintf() verwendet.

Häufige Fallstricke

• Das Array muss mindestens so viele Elemente wie Bezeichner haben. Zu wenige Werte lösen einen ArgumentCountError aus (PHP 8+); zusätzliche Werte werden einfach ignoriert.
• Die Reihenfolge ist entscheidend. Elemente werden positionsweise in Array-Reihenfolge verarbeitet. Um unabhängig von der Reihenfolge auf ein bestimmtes Element zu verweisen, werden nummerierte Platzhalter wie %1$s und %2$d verwendet.
• Die Funktion schreibt, gibt keinen Text zurück. Der Rückgabewert ist eine Zeichenanzahl, kein formatierter String — eine häufige Verwechslung mit vsprintf().
• Der Stream muss beschreibbar sein. Das Öffnen einer Datei mit "r" (Lesemodus) und die Übergabe an vfprintf() schlägt fehl.

Fazit

vfprintf() formatiert einen String und schreibt ihn in einen Stream, wobei die Werte aus einem Array entnommen werden. Die Funktion glänzt, wenn Daten bereits in einem Array gesammelt sind und in eine Datei oder in die Standardausgabe in einem präzisen, spaltenbasierten Format geschrieben werden sollen. Für die Nicht-Stream-Varianten siehe vsprintf() (gibt einen String zurück) und vprintf() (gibt direkt aus), und vergleiche mit fprintf(), wenn die Argumente einzelne Werte anstelle eines Arrays sind.

Übung