PHP substr(): pegar parte de uma string

substr($string, $offset, $length) retorna a parte de $string que começa na posição $offset (contada a partir de 0) e tem $length caracteres. substr('Hello world', 0, 5) retorna "Hello". Deixe de fora $length para pegar tudo até o fim.

<?php
$s = 'Hello world';

echo substr($s, 0, 5), "\n";   // from the start, 5 characters
echo substr($s, 6), "\n";      // from position 6 to the end
echo substr($s, 4, 3), "\n";   // 3 characters from position 4

O substr() conta bytes. Isso é o mesmo que caracteres para texto em inglês, mas não para japonês, chinês, emoji ou letras acentuadas. Para esses, use mb_substr(), mostrado abaixo.

Sintaxe

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

• $offset é onde começar. 0 é o primeiro caractere. Um valor negativo conta a partir do fim.
• $length é quantos bytes pegar (um byte é um caractere em texto ASCII simples). Um valor negativo deixa essa quantidade de fora no fim. null (ou omitir) significa "até o fim".

Offset e tamanho negativos: trabalhar a partir do fim

Um $offset negativo começa a contar a partir do fim da string, então -1 é o último caractere. Um $length negativo para essa quantidade de caracteres antes do fim.

<?php
$file = 'report-2026.pdf';

echo substr($file, -3), "\n";       // last 3 characters
echo substr($file, -8, 4), "\n";    // 4 characters, starting 8 from the end
echo substr($file, 0, -4), "\n";    // everything except the last 4
echo substr($file, 7, -4), "\n";    // from position 7, minus the last 4

substr($s, 0, -1) é o jeito comum de remover o último caractere, por exemplo uma vírgula que sobrou de um loop.

Pegar o primeiro ou o último caractere

Para um único byte, você também pode indexar a string diretamente. $s[0] é o primeiro caractere e, desde o PHP 7.1, $s[-1] é o último.

<?php
$word = 'banana';

echo substr($word, 0, 1), ' ', $word[0], "\n";    // first character
echo substr($word, -1), ' ', $word[-1], "\n";     // last character
echo substr($word, 1), "\n";                     // drop the first character

Indexar uma posição que não existe imprime um aviso, enquanto o substr() só retorna uma string vazia. Se a string puder estar vazia, prefira o substr().

Fora do intervalo: uma string vazia, não false

Se $offset estiver depois do fim da string, o substr() retorna "" no PHP 8. No PHP 7 ele retornava false, então código antigo que verifica === false não funciona mais.

<?php
var_dump(substr('abc', 5));       // start past the end
var_dump(substr('abc', 1, 100));  // length longer than the rest is fine
var_dump(substr('abc', -10));     // negative offset before the start: from 0

Texto em japonês: use mb_substr

O UTF-8 guarda kana e kanji comuns em 3 bytes cada (kanji raros como 𠮷 e emoji ocupam 4). O substr() conta bytes, então substr('こんにちは', 0, 3) retorna só こ, e um tamanho que não cai numa fronteira de caractere corta um caractere ao meio e produz texto quebrado. O mb_substr() recebe os mesmos argumentos e conta caracteres.

<?php
$greeting = 'こんにちは世界';

echo substr($greeting, 0, 3), "\n";       // 3 bytes = 1 character
echo mb_substr($greeting, 0, 3), "\n";    // 3 characters
echo mb_substr($greeting, -2), "\n";      // last 2 characters

// Cutting at 4 bytes splits a character: the result is not valid UTF-8
var_dump(mb_check_encoding(substr($greeting, 0, 4), 'UTF-8'));

O mesmo vale para emoji e letras acentuadas como é. Para contar caracteres, use mb_strlen(); veja strlen() sobre bytes e caracteres.

Encurtar texto com reticências

Cortar um título longo para uma lista ou um card é o uso real mais comum do substr(). Use mb_substr() para que um título em japonês nunca seja cortado no meio de um caractere, e só adicione ... quando você realmente encurtou algo.

<?php
function excerpt(string $text, int $max): string
{
    if (mb_strlen($text) <= $max) {
        return $text;
    }
    return rtrim(mb_substr($text, 0, $max)) . '...';
}

echo excerpt('Short title', 20), "\n";
echo excerpt('A much longer title that will not fit in the card', 20), "\n";
echo excerpt('東京から大阪までの新幹線の旅', 8), "\n";

mb_strimwidth($text, 0, $width, '...') faz o mesmo pela largura de exibição, em que um caractere japonês de largura total conta como 2 colunas e uma letra latina como 1. Serve para layouts de largura fixa.

Contar uma substring com substr_count

substr_count($haystack, $needle) retorna quantas vezes $needle aparece. Ele diferencia maiúsculas e minúsculas e não conta correspondências sobrepostas.

<?php
echo substr_count('banana', 'an'), "\n";
echo substr_count('aaaa', 'aa'), "\n";      // 2, not 3: no overlaps
echo substr_count('Hello hello', 'hello'), "\n";
echo substr_count(strtolower('Hello hello'), 'hello'), "\n";

substr com strpos: texto antes ou depois de um caractere

Combine substr() com strpos() para cortar num caractere cuja posição você não sabe de antemão, como o @ de um endereço de e-mail:

<?php
$email = 'ada.lovelace@example.com';
$at = strpos($email, '@');

echo substr($email, 0, $at), "\n";    // before the @
echo substr($email, $at + 1), "\n";   // after the @

// strstr does the same in one call
echo strstr($email, '@', true), "\n";

Verifique se o strpos() não retornou false antes de usar o resultado: se o caractere não existe, false é tratado como 0 sem aviso, então substr('nobody', 0, $at) retorna "" e substr('nobody', $at + 1) retorna "obody".