PHP sprintf(): formattare stringhe, padding e decimali

sprintf() restituisce una stringa costruita da un formato e da una lista di valori: ogni segnaposto % nel formato viene sostituito dal valore successivo. sprintf('%s is %d years old', 'Ada', 36) restituisce "Ada is 36 years old". printf() accetta gli stessi argomenti ma stampa il risultato invece di restituirlo.

<?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);

I segnaposto vengono riempiti in ordine, da sinistra a destra. %.2f mostra sempre due decimali (4.50, non 4.5), e %05d riempie il numero con zeri fino a cinque cifre.

Gli specificatori di formato

Un segnaposto è %, eventuali modificatori, poi una lettera per il tipo:

Cambia i valori qui sotto ed eseguilo di nuovo:

<?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 tronca un float verso lo zero, quindi 42.9 diventa 42. Se vuoi 43, arrotonda prima: sprintf('%d', round(42.9)). Una stringa che non è un numero, come 'abc', con %d diventa 0.

Riempire con zeri iniziali

Tra % e la lettera puoi mettere un carattere di riempimento e una larghezza. %05d significa "riempi con 0 fino a una larghezza di 5". È il modo consueto di formattare numeri d'ordine, ID di fattura, orari e date.

<?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";

La larghezza è un minimo. Un numero più lungo della larghezza viene stampato per intero.

%05.2f: larghezza e decimali insieme

Con i float, la larghezza conta ogni carattere del risultato, compresi il punto decimale e il segno meno. Ecco perché %05.2f su 3.14159 dà 03.14: cinque caratteri in totale, due dei quali dopo il punto.

<?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 usa il separatore decimale del locale corrente (impostato con setlocale()), mentre %F usa sempre un punto. Se il tuo codice imposta un locale e ti serve un punto per JSON, CSV o un'API, usa %F.

Allineare il testo in colonne

Una larghezza positiva allinea a destra, un - prima della larghezza allinea a sinistra, e ' seguito da un carattere imposta un carattere di riempimento personalizzato. Insieme, allineano report e scontrini in testo semplice.

<?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 riempie a destra il nome dell'articolo fino a 14 caratteri, %8.2f allinea a destra il prezzo in 8 caratteri, e %'-27s con una stringa vuota stampa una riga di 27 trattini. %'*10s riempie con * invece che con spazi.

Numerare gli argomenti per riusarli o riordinarli

%1$s significa "il primo argomento come stringa", %2$d "il secondo come intero". I segnaposto numerati ti permettono di usare un valore due volte o cambiare l'ordine senza cambiare la lista degli argomenti, cosa che serve ai traduttori quando l'ordine delle parole cambia tra le lingue.

<?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 e i valori restituiti

vsprintf() accetta i valori come un unico array, comodo quando si trovano già in un array. printf() restituisce il numero di byte stampati, e vprintf() è la versione di printf() con un array.

<?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);

Il conteggio di printf() include l'a capo, quindi "Hello\n" vale 6 byte. Per il testo multibyte conta i byte, non i caratteri.

Troppi pochi argomenti generano un errore

Da PHP 8, un formato con più segnaposto che valori lancia un ArgumentCountError invece di restituire false. Conta i segnaposto % (ignorando %%) quando vedi questo errore.

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

Il messaggio conta la stringa di formato come argomento: ArgumentCountError: 4 arguments are required, 3 given. Gli argomenti in più vengono ignorati in silenzio, quindi l'errore opposto non compare come errore. Se il risultato di sprintf sembra sbagliato, stampa il formato accanto ai valori. Quando ti serve solo un separatore delle migliaia, number_format() è più semplice che costruirne uno con sprintf. L'elenco completo dei modificatori è su php.net.