vsprintf()

Einführung

Die Funktion vsprintf() in PHP formatiert einen String mithilfe eines Arrays von Argumenten und gibt das Ergebnis zurück, anstatt es auszugeben. Sie funktioniert wie das array-basierte Gegenstück zu sprintf(): Der Formatstring und die Platzhalter funktionieren identisch, aber die Werte stammen aus einem Array statt aus einer Liste einzelner Parameter.

Das „v" im Namen steht für Vektor (Array). Diese Funktion eignet sich, wenn die Werte bereits in einem Array vorliegen — zum Beispiel eine Datenbankzeile, eine geparste CSV-Zeile oder das Ergebnis von explode() — und man sie nicht als einzelne Argumente übergeben möchte.

Dieses Kapitel behandelt die Syntax, die häufigsten Formatbezeichner, reale Formatierungsfälle (Auffüllen, Zahlen, Argument-Neuordnung) sowie den Unterschied zwischen vsprintf() und den verwandten Funktionen der printf/sprintf-Familie.

Syntax

vsprintf(string $format, array $values): string

Der Rückgabewert ist der vollständig formatierte String. Anders als vprintf() wird nichts ausgegeben — es liegt selbst in der Hand, was mit dem zurückgegebenen Wert gemacht wird.

Hinweis: Ab PHP 8.0 wird ein ValueError ausgelöst, wenn zu wenige Werte für die Platzhalter übergeben werden. In früheren Versionen wurde eine Warnung ausgegeben und false zurückgegeben.

Ein erstes Beispiel

Ausgabe:

I like apple, banana, and orange.

Jeder %s-Platzhalter wird von links nach rechts durch das nächste Element von $values ersetzt. Der fertige String wird zurückgegeben und in $result gespeichert — er wird nur ausgegeben, weil explizit echo aufgerufen wird.

Häufige Formatbezeichner

Der Buchstabe nach % bestimmt, wie der zugehörige Wert dargestellt wird:

Bezeichner können zwischen % und dem Buchstaben auch Flags, eine Breite und eine Genauigkeit enthalten (z. B. %05d oder %.2f), wodurch vsprintf() besonders leistungsfähig wird.

Auffüllen und Zahlenformatierung

<?php

// %05d  → pad the integer with zeros to a width of 5
// %01.2f → at least 1 digit, exactly 2 decimal places
// %-10s → left-align the string in a 10-char field
$row = [42, 42.5, 'left'];
echo vsprintf("ID:%05d  Price:\$%01.2f  Name:[%-10s]", $row);

Ausgabe:

ID:00042  Price:$42.50  Name:[left      ]

Das ist der typische Grund für den Einsatz von vsprintf(): Man hat einen Datensatz (hier ein $row-Array) und ein festes Template und möchte ausgerichtete, mit Nullen aufgefüllte Ausgaben im Währungsstil erzeugen, ohne Strings manuell zu verketten.

Argumente mit Positionsplatzhaltern wiederverwenden

Ein Platzhalter der Form %n$ verweist auf das n-te Element des Arrays (1-basiert), sodass derselbe Wert mehrfach verwendet oder die Reihenfolge unabhängig vom Array geändert werden kann:

<?php

$values = ['Sam', 30];
echo vsprintf('%1$s is %2$d years old. Hi %1$s!', $values);

Ausgabe:

Sam is 30 years old. Hi Sam!

Hier wird %1$s zweimal verwendet, obwohl 'Sam' nur einmal im Array vorkommt.

vsprintf() im Vergleich zur restlichen Familie

Diese vier Funktionen verwenden dieselben Formatstring-Regeln; sie unterscheiden sich nur darin, wie Argumente übergeben werden und was mit dem Ergebnis geschieht:

Die Faustregel lautet: Die v*-Variante verwenden, wenn die Daten bereits in einem Array vorliegen, und die sprintf/vsprintf-Variante (ohne das innere print), wenn der String zurückgegeben werden soll statt sofort ausgegeben zu werden.

Häufige Fallstricke

• Zu wenige Werte lösen einen Fehler aus. Wenn das Array weniger Elemente hat als der Formatstring Platzhalter besitzt, wirft PHP 8+ einen ValueError. Die Array-Länge muss mit der Anzahl der (nicht-positionellen) Bezeichner übereinstimmen.
• Zusätzliche Werte werden ignoriert. Mehr Elemente als Platzhalter sind kein Problem — der Überschuss wird stillschweigend verworfen.
• Schlüssel werden bei sequenziellen Platzhaltern ignoriert. vsprintf() verarbeitet das Array nach Position, nicht nach Schlüssel; ein assoziatives Array wird in der Einfügereihenfolge gelesen.
• Literale Prozentzeichen müssen als %% maskiert werden, da PHP andernfalls versucht, das folgende Zeichen als Bezeichner zu lesen.

Verwandte Funktionen

• sprintf() — dieselbe Formatierung mit einzelnen Argumenten.
• vprintf() — wie vsprintf(), gibt das Ergebnis jedoch direkt aus.
• printf() — gibt einen formatierten String aus einzelnen Argumenten aus.
• number_format() — formatiert Zahlen mit gruppierten Tausenderstellen.

Übungen