(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)
vsprintf — Retourne une chaîne formatée
vsprintf() fonctionne comme sprintf(), mais accepte un tableau comme argument, au lieu d'une liste d'arguments.
format
La chaîne de format est composé de zéro ou plusieurs directives :
des caractères ordinaires (à l'exception de %)
qui sont copiés directement dans le résultat et des
spécifications de conversion,
chacun ayant pour résultat de récupérer ses propres paramètre.
Une spécification de conversion qui suit ce prototype :
%[argnum$][flags][width][.precision]specifier.
Un entier suivit d'un signe dollar $,
pour spécifier quel numéro d'argument à traiter dans la conversion.
| Drapeau | Description |
|---|---|
- |
Justifie le texte à gauche donnée la largeur du champ ; Justification à droite est le comportement par défaut. |
+ |
Préfixe les nombres positives avec un signe plus
+ ; Par défaut seul les nombres
négatifs sont préfixés avec un signe négatif.
|
(espace) |
Complète le résultat avec des espaces. Ceci est par défaut. |
0 |
Complète uniquement les nombres à gauches avec des zéros.
Avec le spécificateur s ceci peut aussi
compléter à droite avec des zéros.
|
'(char) |
Complète le résultat avec le caractère (char). |
Soit un entier indiquant le nombre de caractères (minimum)
que cette conversion doit produire, soit *.
Si * est utilisé, alors la largeur est fournie
en tant que valeur entière supplémentaire précédant celle formatée
par le spécificateur.
Un point . suivi optionnellement
soit d'un entier, soit de *,
dont la signification dépend du spécificateur :
e, E,
f et F :
ceci est le nombre de chiffres à afficher après
la virgule (par défaut, ceci est 6).
g, G,
h et H :
ceci est le nombre maximal de chiffres significatifs à afficher.
digits to be printed.
s : il agit comme un point de coupure,
définissant une limite maximale de caractères de la chaîne.
Note: Si le point est spécifié sans une valeur explicite pour la précision, 0 est assumé. Si
*est utilisé, la précision est fournie en tant que valeur entière supplémentaire précédant celle formatée par le spécificateur.
| Spécificateur | Description |
|---|---|
% |
Un caractère de pourcentage littéral. Aucun argument n'est nécessaire. |
b |
L'argument est traité comme un entier et présenté comme un nombre binaire. |
c |
L'argument est traité comme un entier et présenté comme le caractère de code ASCII correspondant. |
d |
L'argument est traité comme un entier et présenté comme un nombre entier décimal (signé). |
e |
L'argument est traité comme une notation scientifique
(e.g. 1.2e+2).
|
E |
Comme le spécificateur e mais utilise
une lettre majuscule (par exemple 1.2E+2).
|
f |
L'argument est traité comme un nombre à virgule flottante (type nombre décimal) et présenté comme un nombre à virgule flottante (tenant compte de la locale utilisée). |
F |
L'argument est traité comme un nombre à virgule flottante (type nombre décimal) et présenté comme un nombre à virgule flottante (ne tenant pas compte de la locale utilisée). |
g |
Format général. Soit P égal à la précision si différent de 0, 6 si la précision est omit ou 1 si la précision est zéro. Alors, si la conversion avec le style E aurait comme exposant X : Si P > X ≥ −4, la conversion est avec style f et précision P − (X + 1). Sinon, la conversion est avec le style e et précision P - 1. |
G |
Comme le spécificateur g mais utilise
E et f.
|
h |
Comme le spécificateur g mais utilise F.
Disponible à partir de PHP 8.0.0.
|
H |
Comme le spécificateur g mais utilise
E et F. Disponible à partir de PHP 8.0.0.
|
o |
L'argument est traité comme un entier et présenté comme un nombre octal. |
s |
L'argument est traité et présenté comme une chaîne de caractères. |
u |
L'argument est traité comme un entier et présenté comme un nombre décimal non signé. |
x |
L'argument est traité comme un entier et présenté comme un nombre hexadécimal (les lettres en minuscules). |
X |
L'argument est traité comme un entier et présenté comme un nombre hexadécimal (les lettres en majuscules). |
Le spécificateur de type c ignore l'alignement et la taille.
Le fait de tenter d'utiliser une combinaison d'une chaîne et de spécificateurs avec des jeux de caractères qui nécessitent plus d'un octet par caractères donnera un résultat inattendu.
Les variables seront contraints à un type approprié pour le spécificateur :
| Type | Spécificateurs |
|---|---|
| string | s |
| int |
d,
u,
c,
o,
x,
X,
b
|
| float |
e,
E,
f,
F,
g,
G,
h,
H
|
values
Retourne une chaîne formatée à partir du tableau de valeurs
values, et en utilisant le format
format.
As of PHP 8.0.0, a ValueError is thrown if the number of arguments is zero.
Prior to PHP 8.0.0, a E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown if [width] is less than zero or bigger than PHP_INT_MAX.
Prior to PHP 8.0.0, a E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown if [precision] is less than zero or bigger than PHP_INT_MAX.
Prior to PHP 8.0.0, a E_WARNING was emitted instead.
As of PHP 8.0.0, a ValueError is thrown when less arguments are given than required.
Prior to PHP 8.0.0, false was returned and a E_WARNING emitted instead.
| Version | Description |
|---|---|
| 8.0.0 |
Cette fonction ne renvoie plus false en cas d'échec.
|
| 8.0.0 |
Lance une ValueError si le nombre d'arguments est zéro ;
auparavant, cette fonction émettait un E_WARNING.
|
| 8.0.0 |
Lance une ValueError si [width] est inférieur à zéro ou supérieur à PHP_INT_MAX ;
auparavant, cette fonction émettait un E_WARNING.
|
| 8.0.0 |
Lance une ValueError si [precision] est inférieur à zéro ou supérieur à PHP_INT_MAX ;
auparavant, cette fonction émettait un E_WARNING.
|
| 8.0.0 |
Lance une ArgumentCountError lorsque moins d'arguments sont donnés que requis ;
auparavant, cette fonction émettait un E_WARNING.
|
Exemple #1 Exemple avec vsprintf() : entiers avec zéro initiaux
<?php
print vsprintf("%04d-%02d-%02d", explode('-', '1988-8-1'));
?>L'exemple ci-dessus va afficher :
1988-08-01
Instead of inventing own functions in case you'd like to use array keys as placeholder names and replace corresponding array values in a string, just use the str_replace:
$string = 'Hello %name!';
$data = array(
'%name' => 'John'
);
$greeting = str_replace(array_keys($data), array_values($data), $string);Note that this function now throws an ValueError* as of PHP 8.0 if there is an error:
$ php -r 'var_dump(vsprintf("%d", []));'
> Fatal error: Uncaught ValueError: The arguments array must contain 1 items, 0 given in Command line code:1
*ValueError is new in PHP 8.0, so if you want to make your code compatible to PHP 7.x you should test that the arguments array has the correct length.<?php
/**
* Like vsprintf, but accepts $args keys instead of order index.
* Both numeric and strings matching /[a-zA-Z0-9_-]+/ are allowed.
*
* Example: vskprintf('y = %y$d, x = %x$1.1f', array('x' => 1, 'y' => 2))
* Result: 'y = 2, x = 1.0'
*
* $args also can be object, then it's properties are retrieved
* using get_object_vars().
*
* '%s' without argument name works fine too. Everything vsprintf() can do
* is supported.
*
* @author Josef Kufner <jkufner(at)gmail.com>
*/
function vksprintf($str, $args)
{
if (is_object($args)) {
$args = get_object_vars($args);
}
$map = array_flip(array_keys($args));
$new_str = preg_replace_callback('/(^|[^%])%([a-zA-Z0-9_-]+)\$/',
function($m) use ($map) { return $m[1].'%'.($map[$m[2]] + 1).'$'; },
$str);
return vsprintf($new_str, $args);
}
?><?php
/**
* Return a formatted string like vsprintf() with named placeholders.
*
* When a placeholder doesn't have a matching key in `$args`,
* the placeholder is returned as is to see missing args.
* @param string $format
* @param array $args
* @param string $pattern
* @return string
*/
function p($format, array $args, $pattern="/\{(\w+)\}/") {
return preg_replace_callback($pattern, function ($matches) use ($args) {
return @$args[$matches[1]] ?: $matches[0];
}, $format);
}
$args = ["database"=>"people", "user"=>"staff", "pass"=>"pass123", "host"=>"localhost"];
// With PHP-like placeholders: the variable is embedded in a string "{$database}" but without the dollar sign
$format = <<<SQL
CREATE DATABASE IF NOT EXISTS {database};
GRANT ALL PRIVILEGES ON {database_name}.* TO '{user}'@'{host}';
SET PASSWORD = PASSWORD('{pass}');
SQL;
echo p($format, $args);
/*
Result:
CREATE DATABASE IF NOT EXISTS people;
GRANT ALL PRIVILEGES ON {database_name}.* TO 'staff'@'localhost';
SET PASSWORD = PASSWORD('pass123');
The `{database_name}` placeholder doesn't exist as a matching key in `$args` so it's returned as is.
*/
// With Ruby-like placeholders
$format = <<<SQL
CREATE DATABASE IF NOT EXISTS :database;
GRANT ALL PRIVILEGES ON :database_name.* TO ':user'@':host';
SET PASSWORD = PASSWORD(':pass');
SQL;
echo p($format, $args, "/:(\w+)/");
/*
Result:
CREATE DATABASE IF NOT EXISTS people;
GRANT ALL PRIVILEGES ON :database_name.* TO 'staff'@'localhost';
SET PASSWORD = PASSWORD('pass123');
The `:database_name` placeholder doesn't exist as a matching key in `$args` so it's returned as is.
*/vnsprintf is equal to vsprintf except for associative, signed or floating keys.
vnsprintf supports for example "%assocKey$05d", "%-2$'+10s" and "%3.2$05u", vsprintf doesn't
vnsprintf( '%2$d', $array) [2nd value] is equal to vsprintf( '%2$d', $array) [2nd value]
vnsprintf( '%+2$d', $array) [key = 2] is equal to vnsprintf( '%2.0$d', $array) [key = 2]
vnsprintf( '%+2$d', $array) [key = 2] is different of vsprintf( '%+2$d', $array) [unsupported]
When you use signed or floating keys, vnsprintf searchs for the signed truncated key of the original array
Note¹: vnsprintf does not support for example "%someKeyf" (floating number, key = someKey) or "%+03d" (signed decimal number, key = 3), you should use "%someKey$f" or "%+03$d" respectively.
Note²: "%+03d" (or "%1$+03d") will be interpreted as signed zero-padded decimal number
<?php
function vnsprintf( $format, array $data)
{
preg_match_all( '/ (?<!%) % ( (?: [[:alpha:]_-][[:alnum:]_-]* | ([-+])? [0-9]+ (?(2) (?:\.[0-9]+)? | \.[0-9]+ ) ) ) \$ [-+]? \'? .? -? [0-9]* (\.[0-9]+)? \w/x', $format, $match, PREG_SET_ORDER | PREG_OFFSET_CAPTURE);
$offset = 0;
$keys = array_keys($data);
foreach ( $match as &$value )
{
if ( ( $key = array_search( $value[1][0], $keys) ) !== FALSE || ( is_numeric( $value[1][0]) && ( $key = array_search( (int)$value[1][0], $keys) ) !== FALSE ) ) {
$len = strlen( $value[1][0]);
$format = substr_replace( $format, 1 + $key, $offset + $value[1][1], $len);
$offset -= $len - strlen( $key);
}
}
return vsprintf( $format, $data);
}
$examples = array(
2.8=>'positiveFloat', // key = 2 , 1st value
-3=>'negativeInteger', // key = -3 , 2nd value
'my_name'=>'someString' // key = my_name , 3rd value
);
echo vsprintf( "%%my_name\$s = '%my_name\$s'\n", $examples); // [unsupported]
echo vnsprintf( "%%my_name\$s = '%my_name\$s'\n", $examples); // output : "someString"
echo vsprintf( "%%2.5\$s = '%2.5\$s'\n", $examples); // [unsupported]
echo vnsprintf( "%%2.5\$s = '%2.5\$s'\n", $examples); // output : "positiveFloat"
echo vsprintf( "%%+2.5\$s = '%+2.5\$s'\n", $examples); // [unsupported]
echo vnsprintf( "%%+2.5\$s = '%+2.5\$s'\n", $examples); // output : "positiveFloat"
echo vsprintf( "%%-3.2\$s = '%-3.2\$s'\n", $examples); // [unsupported]
echo vnsprintf( "%%-3.2\$s = '%-3.2\$s'\n", $examples); // output : "negativeInteger"
echo vsprintf( "%%2\$s = '%2\$s'\n", $examples); // output : "negativeInteger"
echo vnsprintf( "%%2\$s = '%2\$s'\n", $examples); // output : [= vsprintf]
echo vsprintf( "%%+2\$s = '%+2\$s'\n", $examples); // [unsupported]
echo vnsprintf( "%%+2\$s = '%+2\$s'\n", $examples); // output : "positiveFloat"
echo vsprintf( "%%-3\$s = '%-3\$s'\n", $examples); // [unsupported]
echo vnsprintf( "%%-3\$s = '%-3\$s'\n", $examples); // output : "negativeInteger"
?>This can be used for quick and dirty internationalization:
<?php
$GLOBALS['strings']['example'] = "There are %d people.";
// Loads a phrase from the translations list in lang/$lang/phrases.php
function t() {
$args = func_get_args();
$nArgs = func_num_args();
$phrase = array_shift($args);
$nArgs--;
include_once("../lang/" . lang() . "/phrases.php");
if (isset($GLOBALS['strings'][$phrase])) {
return vsprintf($GLOBALS['strings'][$phrase], $args);
} else {
return '<span style="color: #ff0000">Untranslated string: ' . $phrase . '</span>';
}
}
?>Please note: The same functionality (sortof) can be attained between version 4.0.4 and 4.1.0 using call_user_func_array.
Example:
call_user_func_array("sprintf", $arg)
First element of $arg is the format. This rescued me in a situation where version 4.1.0 wasn't available.Using a heredoc with vprintf:
<?php
$string = <<<THESTRING
I like the state of %1\$s <br />
I picked: %2\$d as a number, <br />
I also picked %2\$d as a number again <br />
%3\$s<br />
THESTRING;
$returnText = vprintf( $string, array('Oregon','7','I Love Oregon') );
echo $returnText;
?>vsprintf() accepts arrays with any keys, so the array_shift() technique is unnecessary when writing a printf-type function. Any parameters you require are easily unset from the array you retrieve with func_get_args():
<?php
function mysprintf($format) {
$args = func_get_args();
unset($args[0]); /* get rid of "$format" */
return vsprintf($format, $args);
}
/* I use this technique in production code as follows: */
function logf($target, $string) {
$args = func_get_args();
unset($args[0], $args[1]);
fprintf($GLOBALS['config']['logtargets'][$target],
"[%s] %s\n", date('H:i'), wordwrap(vsprintf($string, $args), 75, '\n\r '));
}
/* e.g.:
logf(DEBUG, "Oops! %s", mysql_error());
*/
?>
array_shift() and other costly array operations aren't required, as far as I know. I could be wrong.It's necessary to clearly how to apply argument swapping when using an array of arguments. One might be tempted to use %0$ to reference $args[0].
In reality, the position specifier is always the array index+1:
$args[0] is referenced by %1$...
$args[1] is referenced by %2$...
etc.
Similarly, the first subpattern of a RegEx match would be found in $matches[1], the second in $match[2], etc. However if the $matches array is used as arguments to vsprint(), then the position specifier is subpattern+1:
preg_match( $pattern, $subject, $matches );
vsprintf( 'Full Match = %1$s, first Subpattern = %2$s, second Subpattern = %3$s', $matches );