PHP sprintf() : formater des chaînes, zéros et décimales

sprintf() renvoie une chaîne construite à partir d'un format et d'une liste de valeurs : chaque marqueur % du format est remplacé par la valeur suivante. sprintf('%s is %d years old', 'Ada', 36) renvoie "Ada is 36 years old". printf() prend les mêmes arguments mais affiche le résultat au lieu de le renvoyer.

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

Les marqueurs sont remplis dans l'ordre, de gauche à droite. %.2f affiche toujours deux décimales (4.50, pas 4.5), et %05d complète le nombre avec des zéros jusqu'à cinq chiffres.

Les spécificateurs de format

Un marqueur s'écrit %, des modificateurs facultatifs, puis une lettre pour le type :

Modifiez les valeurs ci-dessous et relancez :

<?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 tronque un float vers zéro, donc 42.9 devient 42. Si vous voulez 43, arrondissez d'abord : sprintf('%d', round(42.9)). Une chaîne qui n'est pas un nombre, comme 'abc', devient 0 avec %d.

Compléter avec des zéros devant

Entre % et la lettre, vous pouvez placer un caractère de remplissage et une largeur. %05d signifie « compléter avec 0 jusqu'à une largeur de 5 ». C'est la façon habituelle de formater des numéros de commande, des numéros de facture, des heures et des dates.

<?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 largeur est un minimum. Un nombre plus long que la largeur est affiché en entier.

%05.2f : largeur et décimales ensemble

Avec les floats, la largeur compte chaque caractère du résultat, y compris le point décimal et le signe moins. C'est pourquoi %05.2f sur 3.14159 donne 03.14 : cinq caractères au total, dont deux après le point.

<?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 utilise le séparateur décimal de la locale courante (définie avec setlocale()), alors que %F utilise toujours un point. Si votre code définit une locale et qu'il vous faut un point pour du JSON, du CSV ou une API, utilisez %F.

Aligner du texte en colonnes

Une largeur positive aligne à droite, un - avant la largeur aligne à gauche, et ' suivi d'un caractère définit un caractère de remplissage personnalisé. Combinés, ils alignent des rapports en texte brut et des tickets de caisse.

<?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 complète le nom de l'article à droite jusqu'à 14 caractères, %8.2f aligne le prix à droite sur 8 caractères, et %'-27s avec une chaîne vide affiche une ligne de 27 tirets. %'*10s remplit avec * au lieu d'espaces.

Numéroter les arguments pour les réutiliser ou les réordonner

%1$s signifie « le premier argument en tant que chaîne », %2$d « le second en tant qu'entier ». Les marqueurs numérotés permettent d'utiliser une valeur deux fois ou de changer l'ordre sans changer la liste d'arguments, ce dont les traducteurs ont besoin quand l'ordre des mots diffère d'une langue à l'autre.

<?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 et les valeurs de retour

vsprintf() prend les valeurs sous forme d'un seul tableau, pratique quand elles sont déjà dans un tableau. printf() renvoie le nombre d'octets affichés, et vprintf() est la version tableau de 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);

Le compte renvoyé par printf() inclut le saut de ligne, donc "Hello\n" fait 6 octets. Pour du texte multioctet, il compte des octets, pas des caractères.

Trop peu d'arguments lève une erreur

Depuis PHP 8, un format avec plus de marqueurs que de valeurs lève une ArgumentCountError au lieu de renvoyer false. Comptez les marqueurs % (en ignorant %%) quand vous voyez cette erreur.

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

Le message compte la chaîne de format comme un argument : ArgumentCountError: 4 arguments are required, 3 given. Les arguments en trop sont ignorés sans bruit, donc l'erreur inverse ne se voit pas. Si un résultat de sprintf semble faux, affichez le format à côté des valeurs. Quand vous avez seulement besoin d'un séparateur de milliers, number_format() est plus simple que d'en construire un avec sprintf. La liste complète des modificateurs est sur php.net.