str_repeat()

A função PHP str_repeat() retorna uma nova string formada pela repetição de uma string fornecida um número específico de vezes. É útil para construir padrões repetidos como linhas separadoras, recuos, barras de progresso ou preenchimento, sem precisar digitar os mesmos caracteres repetidamente.

Este capítulo aborda a sintaxe, os parâmetros, o valor de retorno e os casos especiais a serem conhecidos, com exemplos executáveis.

Sintaxe

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

Parâmetros

A função aceita dois parâmetros obrigatórios:

• $string — a string a ser repetida. Pode ser um único caractere ou uma string mais longa.
• $times — quantas vezes repeti-la. Deve ser 0 ou maior.

Valor de retorno

str_repeat() retorna a string repetida. Se $times for 0, retorna uma string vazia (""). Passar um número negativo gera um ValueError no PHP 8.0 e posterior (em versões anteriores, disparava um aviso e retornava uma string vazia).

Exemplo básico

Aqui a string "Hello" é repetida três vezes, produzindo HelloHelloHello. Note que as partes são unidas sem separador entre elas — str_repeat() simplesmente concatena as cópias.

A saída deste código será:

HelloHelloHello

Usos práticos

Desenhando uma linha separadora

Um uso comum é gerar um divisor de largura fixa, em vez de digitar o mesmo caractere dezenas de vezes:

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

Saída:

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

Recuo e preenchimento

Repita espaços (ou qualquer string) para recuar o texto em um nível:

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

Saída:

        nested item

Se você precisar apenas preencher uma string até um comprimento total fixo (em vez de repetir uma quantidade fixa), use str_pad() — ele cuida do cálculo da largura para você.

Casos especiais

• Zero repetições retornam uma string vazia:

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

• Repetir uma string vazia sempre produz uma string vazia, independentemente do contador:

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

Funções relacionadas

• str_pad() — preenche uma string até um comprimento alvo.
• str_replace() — substitui ocorrências dentro de uma string.
• strrev() — inverte uma string.
• strlen() — obtém o comprimento de uma string.
• implode() — une elementos de um array com uma string de cola.

Prática