PHP sprintf(): Strings formatieren, Padding, Dezimalen

sprintf() liefert einen String, der aus einem Format und einer Liste von Werten gebaut wird: Jeder %-Platzhalter im Format wird durch den nächsten Wert ersetzt. sprintf('%s is %d years old', 'Ada', 36) liefert "Ada is 36 years old". printf() nimmt dieselben Argumente, gibt das Ergebnis aber aus, statt es zurückzugeben.

<?php
$name = 'Ada';
$age = 36;
$price = 4.5;

$line = sprintf('%s is %d years old', $name, $age);
echo $line, "\n";

// Two decimals, always
echo sprintf('Total: %.2f EUR', $price), "\n";

// printf prints directly
printf("Order #%05d for %s\n", 42, $name);

Die Platzhalter werden der Reihe nach von links nach rechts gefüllt. %.2f zeigt immer zwei Nachkommastellen (4.50, nicht 4.5), und %05d füllt die Zahl mit Nullen auf fünf Stellen auf.

Die Formatangaben

Ein Platzhalter besteht aus %, optionalen Modifikatoren und dann einem Buchstaben für den Typ:

Ändere die Werte unten und führe den Code erneut aus:

<?php
echo sprintf('%s', 'PHP'), "\n";
echo sprintf('%d', 42.9), "\n";      // the decimals are cut off, not rounded
echo sprintf('%f', 1.5), "\n";
echo sprintf('%.2f', 1.5), "\n";
echo sprintf('%e', 1234.5678), "\n";
echo sprintf('%x %X', 255, 255), "\n";
echo sprintf('%o', 8), "\n";
echo sprintf('%b', 5), "\n";
echo sprintf('%08b', 5), "\n";       // binary padded to 8 bits
echo sprintf('%c', 65), "\n";
echo sprintf('%d%%', 50), "\n";
echo sprintf('%+d %+d', 5, -5), "\n"; // always show the sign

%d schneidet einen Float in Richtung null ab, also wird 42.9 zu 42. Wenn du 43 willst, rundest du vorher: sprintf('%d', round(42.9)). Ein String, der keine Zahl ist, etwa 'abc', wird unter %d zu 0.

Mit führenden Nullen auffüllen

Zwischen % und den Buchstaben kannst du ein Füllzeichen und eine Breite setzen. %05d bedeutet „mit 0 auf eine Breite von 5 auffüllen“. So formatiert man üblicherweise Bestellnummern, Rechnungs-IDs, Uhrzeiten und Datumsangaben.

<?php
echo sprintf('%05d', 42), "\n";         // 00042
echo sprintf('%03d', 7), "\n";          // 007
echo sprintf('INV-%06d', 1234), "\n";   // INV-001234

// Times and dates from numbers
$h = 9; $m = 5; $s = 3;
echo sprintf('%02d:%02d:%02d', $h, $m, $s), "\n";
echo sprintf('%04d-%02d-%02d', 2026, 3, 14), "\n";

// A width smaller than the number never cuts it
echo sprintf('%03d', 123456), "\n";

Die Breite ist ein Minimum. Eine Zahl, die länger als die Breite ist, wird vollständig ausgegeben.

%05.2f: Breite und Nachkommastellen zusammen

Bei Floats zählt die Breite jedes Zeichen des Ergebnisses, auch den Dezimalpunkt und das Minuszeichen. Deshalb ergibt %05.2f bei 3.14159 den Wert 03.14: insgesamt fünf Zeichen, zwei davon nach dem Punkt.

<?php
$pi = 3.14159;

echo sprintf('%05.2f', $pi), "\n";   // 5 characters in total
echo sprintf('%08.2f', $pi), "\n";   // 8 characters in total
echo sprintf('%.2f', $pi), "\n";     // no width, just 2 decimals
echo sprintf('%.0f', $pi), "\n";     // no decimals
echo sprintf('%.2f', 5), "\n";       // integers get decimals too
echo sprintf('%08.2f', -3.5), "\n";  // the minus sign counts

%f verwendet den Dezimalpunkt der aktuellen Locale (gesetzt mit setlocale()), während %F immer einen Punkt verwendet. Wenn dein Code eine Locale setzt und du für JSON, CSV oder eine API einen Punkt brauchst, verwende %F.

Text in Spalten ausrichten

Eine positive Breite richtet rechtsbündig aus, ein - vor der Breite linksbündig, und ' gefolgt von einem Zeichen setzt ein eigenes Füllzeichen. Zusammen bringen sie Textberichte und Kassenbons in Reih und Glied.

<?php
$items = [
    ['Coffee', 2, 3.5],
    ['Croissant', 1, 2.25],
    ['Orange juice', 3, 4],
];

printf("%-14s %3s %8s\n", 'Item', 'Qty', 'Price');
printf("%'-27s\n", '');

$total = 0;
foreach ($items as [$name, $qty, $price]) {
    $line = $qty * $price;
    $total += $line;
    printf("%-14s %3d %8.2f\n", $name, $qty, $line);
}

printf("%'-27s\n", '');
printf("%-14s %12.2f\n", 'Total', $total);
printf("[%'*10s]\n", 'stars');

%-14s füllt den Artikelnamen rechts auf 14 Zeichen auf, %8.2f richtet den Preis rechtsbündig in 8 Zeichen aus, und %'-27s mit einem leeren String gibt eine Linie aus 27 Bindestrichen aus. %'*10s füllt mit * statt mit Leerzeichen auf.

Argumente nummerieren, um sie wiederzuverwenden oder umzuordnen

%1$s bedeutet „das erste Argument als String“, %2$d „das zweite als Ganzzahl“. Mit nummerierten Platzhaltern kannst du einen Wert zweimal verwenden oder die Reihenfolge ändern, ohne die Argumentliste zu ändern, und das brauchen Übersetzer, wenn sich die Wortstellung zwischen Sprachen unterscheidet.

<?php
// Single quotes: in double quotes PHP would read $s as a variable
$format = '%1$s has %2$d new messages. Open them, %1$s?';
echo sprintf($format, 'Ada', 3), "\n";

// Same arguments, different order in the sentence
$en = 'Page %1$d of %2$d';
$ja = '全%2$dページ中%1$dページ目';
echo sprintf($en, 2, 10), "\n";
echo sprintf($ja, 2, 10), "\n";

// Modifiers go after the $
echo sprintf('%1$05.1f / %1$.3f', 2.71828), "\n";

vsprintf, printf und die Rückgabewerte

vsprintf() nimmt die Werte als ein Array, was praktisch ist, wenn sie schon in einem Array stehen. printf() liefert die Anzahl der ausgegebenen Bytes, und vprintf() ist die Array-Version von printf().

<?php
$row = ['Ada', 'Lovelace', 1815];
echo vsprintf("%s %s was born in %d.\n", $row);

$bytes = printf("%s\n", 'Hello');
echo "printf printed $bytes bytes\n";

// Same result, two ways
echo sprintf('%.1f%%', 12.345), "\n";
printf("%.1f%%\n", 12.345);

Die Zahl von printf() schließt den Zeilenumbruch ein, also sind "Hello\n" 6 Bytes. Bei Multibyte-Text zählt sie Bytes, nicht Zeichen.

Zu wenige Argumente werfen einen Fehler

Seit PHP 8 wirft ein Format mit mehr Platzhaltern als Werten einen ArgumentCountError, statt false zu liefern. Zähle die %-Platzhalter (ohne %%), wenn du diesen Fehler siehst.

<?php
// This throws an ArgumentCountError on purpose: 3 placeholders, 2 values
echo sprintf('%s bought %d items for %.2f', 'Ada', 3);

Die Meldung zählt den Format-String als Argument mit: ArgumentCountError: 4 arguments are required, 3 given. Überzählige Argumente werden still ignoriert, also zeigt sich der umgekehrte Fehler nicht als Fehler. Wenn ein Ergebnis von sprintf falsch aussieht, gib das Format neben den Werten aus. Wenn du nur ein Tausendertrennzeichen brauchst, ist number_format() einfacher, als eines mit sprintf zu bauen. Die vollständige Liste der Modifikatoren steht auf php.net.