str_pad() - Aprender PHP

La función PHP str_pad() rellena una cadena con otra cadena hasta que alcanza una longitud determinada. Se usa cuando la salida necesita un ancho fijo: números con ceros a la izquierda (007), alineación de columnas en un informe, construcción de registros de ancho fijo para sistemas heredados o centrado de etiquetas dentro de un banner.

Esta página cubre la sintaxis, cada modo de relleno, las reglas que suelen confundir y ejemplos prácticos que puedes ejecutar.

Sintaxis

str_pad(string $string, int $length, string $pad_string = " ", int $pad_type = STR_PAD_RIGHT): string

Parámetros

Parámetro	Requerido	Descripción
`$string`	Sí	La cadena de entrada a rellenar.
`$length`	Sí	La longitud objetivo del resultado. Si es menor o igual que la longitud actual de `$string`, no se produce relleno y se devuelve `$string` sin cambios.
`$pad_string`	No	La cadena utilizada para rellenar el hueco. Por defecto es un espacio simple. Puede tener más de un carácter.
`$pad_type`	No	Dónde agregar el relleno: `STR_PAD_RIGHT` (por defecto), `STR_PAD_LEFT` o `STR_PAD_BOTH`.

La función devuelve la cadena rellenada. Nunca la trunca: solo la hace más larga o la devuelve tal cual.

Ejemplo básico: rellenar un número con ceros

Un uso habitual es forzar un número a un ancho fijo rellenándolo con ceros iniciales.

php— editable, runs on the server

"Hello" tiene 5 caracteres y pedimos una longitud de 10, por lo que str_pad() añade 5 caracteres "0" a la izquierda:

00000Hello

Los tres modos de relleno

El cuarto argumento controla qué lado recibe el relleno.

<?php
echo str_pad("Hi", 8, "-", STR_PAD_RIGHT), "\n"; // Hi------
echo str_pad("Hi", 8, "-", STR_PAD_LEFT),  "\n"; // ------Hi
echo str_pad("Hi", 8, "-", STR_PAD_BOTH),  "\n"; // ---Hi---
?>

Salida:

Hi------
------Hi
---Hi---

Con STR_PAD_BOTH, el relleno se divide entre los dos lados. Cuando el número de caracteres de relleno es impar, el extra va a la derecha:

<?php
echo str_pad("Hi", 7, "-", STR_PAD_BOTH), "\n"; // --Hi---
?>

Ejemplo práctico: alinear un informe

Dado que str_pad() produce columnas de ancho fijo, es muy útil para tablas en texto plano. Rellena las etiquetas a la derecha y los números a la izquierda:

<?php
$items = ["Apples" => 3, "Bread" => 12, "Milk" => 1];

foreach ($items as $name => $qty) {
    echo str_pad($name, 10) . str_pad($qty, 5, " ", STR_PAD_LEFT) . "\n";
}
?>

Salida:

Apples        3
Bread        12
Milk          1

Advertencias y notas

Nunca reduce una cadena. Si $length es menor que la entrada, str_pad() devuelve la entrada sin cambios. Usa substr() si también necesitas limitar la longitud.
Las cadenas de relleno de varios caracteres pueden pasarse, pero str_pad() las recorta. Rellenar "x" hasta la longitud 6 con "ab" produce "xababa": la cadena de relleno se repite y se corta exactamente en la longitud objetivo.
Cuenta bytes, no caracteres. Con texto multibyte (UTF-8), un carácter acentuado o no latino puede ocupar varios bytes, por lo que el ancho visible puede diferir de $length. No existe una función mb_str_pad() integrada antes de PHP 8.3.
Para números con ceros, sprintf() con un formato como %05d suele ser más claro que str_pad().

Funciones relacionadas

str_repeat() — repetir una cadena un número fijo de veces.
sprintf() — formatear cadenas con especificadores de ancho y precisión.
number_format() — formatear números con miles agrupados y decimales.
strlen() — obtener la longitud que str_pad() utiliza como referencia.
trim() — la idea inversa: eliminar caracteres del entorno.

Práctica

¿Qué hace la función PHP str_pad()?

Rellena una cadena por la derecha con otra cadena.Rellena una cadena por la izquierda con otra cadena.Rellena una cadena por ambos lados con otra cadena.Recorta una cadena con otra cadena.Reemplaza una parte de una cadena con otra cadena.