substr()

A função substr() retorna uma fatia de uma string — os caracteres entre uma posição inicial e um comprimento opcional. É uma das ferramentas de string mais usadas em PHP: cortar prefixos, pegar os primeiros N caracteres de um rótulo, ler um campo de largura fixa ou obter uma extensão de arquivo — tudo isso se resume a uma chamada substr(). Esta página cobre a sintaxe, todas as formas como os argumentos $start e $length se comportam (incluindo valores negativos), os casos extremos que confundem as pessoas e quando usar mb_substr() em vez disso.

Sintaxe

substr(string $string, int $offset, ?int $length = null): string

substr() retorna a substring extraída. A partir do PHP 8.0, sempre retorna uma string (uma string vazia quando nada corresponde); antes do PHP 8.0, retornava false em caso de falha, portanto você ainda pode ver isso em código mais antigo.

Um exemplo básico

$offset é 0, então a extração começa no primeiro caractere, e $length é 5, portanto cinco caracteres (Hello) são retornados. Lembre-se de que o deslocamento é baseado em zero: a posição 0 é H, a posição 1 é e, e assim por diante.

Como o deslocamento funciona

Um deslocamento positivo conta a partir do início; um deslocamento negativo conta a partir do final (onde -1 é o último caractere):

<?php
$string = "Hello World!";

echo substr($string, 6);   // World!  — from offset 6 to the end
echo "\n";
echo substr($string, -6);  // World!  — last 6 characters
echo "\n";
echo substr($string, -1);  // !       — just the last character

Omitir $length retorna tudo a partir do deslocamento em diante — útil para remover um prefixo conhecido.

Como o comprimento funciona

Um $length positivo limita quantos caracteres você pega. Um $length negativo para esse número de caracteres antes do final da string, o que é ótimo para remover um sufixo conhecido:

<?php
$string = "Hello World!";

echo substr($string, 0, -1);   // Hello World  — drop the trailing "!"
echo "\n";
echo substr($string, -6, 5);   // World        — start 6 from the end, take 5
echo "\n";
echo substr($string, 4, 0);    // (empty)      — length 0 returns ""

Se o comprimento solicitado ultrapassar o final da string, substr() simplesmente retorna o que estiver disponível — nunca gera erro por ser "longo demais."

Uso prático: uma extensão de arquivo

Combinar substr() com strrpos() (que encontra a última posição de um caractere) é a forma clássica de obter uma extensão de arquivo:

<?php
$filename = "report.final.pdf";
$ext = substr($filename, strrpos($filename, ".") + 1);

echo $ext; // pdf

Armadilhas comuns

• Deslocamento fora do intervalo. Se $offset for maior que o comprimento da string, você obtém uma string vazia (no PHP 8+). Não há arredondamento.
• Conta bytes, não caracteres. substr() opera em bytes. Para texto UTF-8 com letras acentuadas ou emoji, fatiar no meio de um caractere produz resultados inválidos. Use mb_substr() para extração segura com multibyte.
• Erro de um a mais com o comprimento. $length é uma contagem, não um índice final. substr($s, 2, 3) retorna 3 caracteres começando no índice 2 — não os caracteres entre o índice 2 e o índice 3.

Funções relacionadas

• strlen() — obtém o comprimento de uma string, frequentemente usado para calcular um $length.
• strpos() — encontra onde uma substring começa, para alimentar o substr().
• explode() — divide uma string em um array quando há um delimitador.
• trim() — remove espaços em branco (ou outros caracteres) de ambas as extremidades.

Prática