str_repeat()

La función PHP str_repeat() devuelve una nueva cadena formada al repetir una cadena dada un número determinado de veces. Es muy útil para construir patrones repetidos como líneas separadoras, sangría, barras de progreso o relleno, sin necesidad de escribir los mismos caracteres una y otra vez.

Este capítulo cubre la sintaxis, los parámetros, el valor de retorno y los casos límite que vale la pena conocer, con ejemplos ejecutables.

Sintaxis

str_repeat(string $string, int $times): string

Parámetros

La función recibe dos parámetros obligatorios:

• $string — la cadena a repetir. Puede ser un solo carácter o una cadena más larga.
• $times — cuántas veces repetirla. Debe ser 0 o mayor.

Valor de retorno

str_repeat() devuelve la cadena repetida. Si $times es 0, devuelve una cadena vacía (""). Pasar un número negativo genera un ValueError en PHP 8.0 y versiones posteriores (en versiones anteriores generaba una advertencia y devolvía una cadena vacía).

Ejemplo básico

Aquí la cadena "Hello" se repite tres veces, produciendo HelloHelloHello. Nótese que las partes se unen sin ningún separador entre ellas — str_repeat() simplemente concatena las copias.

La salida de este código será:

HelloHelloHello

Usos prácticos

Dibujar una línea separadora

Un uso habitual es generar un divisor de ancho fijo, en lugar de escribir el mismo carácter decenas de veces:

<?php
echo str_repeat("=", 20) . "\n";
echo "  Report\n";
echo str_repeat("=", 20) . "\n";
?>

Salida:

====================
  Report
====================

Sangría y relleno

Repite espacios (o cualquier cadena) para indentar texto por niveles:

<?php
$level = 2;
$indent = str_repeat("    ", $level); // 4 spaces per level
echo $indent . "nested item\n";
?>

Salida:

        nested item

Si solo necesitas rellenar una cadena hasta una longitud total fija (en lugar de repetir un número fijo de veces), usa str_pad() — se encarga del cálculo del ancho por ti.

Casos límite

• Cero repeticiones devuelven una cadena vacía:

<?php
var_dump(str_repeat("abc", 0)); // string(0) ""
?>

• Repetir una cadena vacía siempre produce una cadena vacía, independientemente del contador:

<?php
var_dump(str_repeat("", 5)); // string(0) ""
?>

Funciones relacionadas

• str_pad() — rellena una cadena hasta una longitud objetivo.
• str_replace() — reemplaza ocurrencias dentro de una cadena.
• strrev() — invierte una cadena.
• strlen() — obtiene la longitud de una cadena.
• implode() — une elementos de un array con una cadena de unión.

Práctica