vsprintf()
La función vsprintf() en PHP formatea una cadena usando un array de argumentos y devuelve el resultado en lugar de imprimirlo.
Introducción
La función vsprintf() en PHP formatea una cadena usando un array de argumentos y devuelve el resultado en lugar de imprimirlo. Funciona como el gemelo basado en arrays de sprintf(): la cadena de formato y los marcadores de posición funcionan de forma idéntica, pero los valores provienen de un array en lugar de una lista de parámetros separados.
La "v" en el nombre significa vector (array). Esta es la función a utilizar cuando los valores ya se encuentran en un array — por ejemplo, una fila de base de datos, una línea CSV analizada o el resultado de explode() — y no deseas expandirlos como argumentos individuales.
Este capítulo cubre la sintaxis, los especificadores de formato más comunes, casos de formato reales (relleno, números, reordenación de argumentos) y cómo vsprintf() se diferencia de la familia relacionada printf/sprintf.
Sintaxis
vsprintf(string $format, array $values): string| Parámetro | Descripción |
|---|---|
$format | Una cadena de plantilla que contiene texto literal más marcadores de posición (también llamados especificadores de formato) que comienzan con el carácter %. |
$values | Un array cuyos elementos se sustituyen en los marcadores de posición, en orden. |
El valor de retorno es la cadena completamente formateada. A diferencia de vprintf(), nada se envía a la salida — tú decides qué hacer con el valor devuelto.
Nota: A partir de PHP 8.0, pasar muy pocos valores para los marcadores de posición lanza un
ValueError. En versiones anteriores, generaba una advertencia y devolvíafalse.
Un primer ejemplo
Salida:
I like apple, banana, and orange.Cada marcador de posición %s se reemplaza, de izquierda a derecha, con el siguiente elemento de $values. La cadena terminada se devuelve y se almacena en $result — solo se imprime porque llamamos explícitamente a echo.
Especificadores de formato más comunes
La letra después de % controla cómo se renderiza el valor correspondiente:
| Especificador | Significado | Valor de ejemplo → salida |
|---|---|---|
%s | String | 'hi' → hi |
%d | Entero con signo | 42.9 → 42 |
%f | Punto flotante | 3.5 → 3.500000 |
%b | Binario | 5 → 101 |
%x | Hexadecimal en minúsculas | 255 → ff |
%% | Un signo de porcentaje literal | → % |
Los especificadores también pueden llevar indicadores, un ancho y una precisión entre el % y la letra (por ejemplo %05d o %.2f), que es donde vsprintf() se vuelve verdaderamente poderosa.
Relleno y formato de números
<?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);Salida:
ID:00042 Price:$42.50 Name:[left ]Esta es la razón típica para elegir vsprintf(): tienes un registro (aquí un array $row) y una plantilla fija, y deseas una salida alineada, con ceros a la izquierda y con formato de moneda sin concatenar cadenas manualmente.
Reutilización de argumentos con marcadores de posición posicionales
Un marcador de posición de la forma %n$ se refiere al n-ésimo elemento del array (base 1), por lo que puedes usar el mismo valor más de una vez o cambiar su orden independientemente del array:
<?php
$values = ['Sam', 30];
echo vsprintf('%1$s is %2$d years old. Hi %1$s!', $values);Salida:
Sam is 30 years old. Hi Sam!Aquí %1$s se usa dos veces, aunque 'Sam' aparece solo una vez en el array.
vsprintf() vs. el resto de la familia
Estas cuatro funciones comparten exactamente las mismas reglas de cadena de formato; difieren solo en cómo se pasan los argumentos y qué hacen con el resultado:
| Función | Argumentos | Resultado |
|---|---|---|
sprintf() | Parámetros separados | Devuelve la cadena |
printf() | Parámetros separados | Imprime y devuelve la longitud |
vsprintf() | Un array | Devuelve la cadena |
vprintf() | Un array | Imprime y devuelve la longitud |
La regla general es: usa la variante v* cuando los datos ya están en un array, y usa las variantes sprintf/vsprintf (sin el print interno) cuando quieras recuperar la cadena en lugar de imprimirla inmediatamente.
Errores comunes
- Muy pocos valores generan un error. Si el array tiene menos elementos que marcadores de posición en el formato, PHP 8+ lanza un
ValueError. Asegúrate de que la longitud del array coincida con el número de especificadores (no posicionales). - Los valores extra se ignoran. Tener más elementos que marcadores de posición está bien — el excedente se descarta silenciosamente.
- Las claves se ignoran para los marcadores de posición secuenciales.
vsprintf()consume el array por posición, no por clave, por lo que un array asociativo se lee en orden de inserción. - Escapa los signos de porcentaje literales como
%%, de lo contrario PHP intenta leer el siguiente carácter como especificador.
Funciones relacionadas
sprintf()— el mismo formato con argumentos separados.vprintf()— comovsprintf()pero imprime el resultado directamente.printf()— imprime una cadena formateada a partir de argumentos separados.number_format()— formatea números con miles agrupados.