strchr()

A função PHP strchr() encontra a primeira ocorrência de uma substring dentro de uma string e retorna o restante da string a partir desse ponto. Apesar do nome (que remete ao strchr do C), o "needle" (agulha) que você busca pode ter mais de um caractere. Esta página cobre a sintaxe, o parâmetro opcional $before_needle, o valor de retorno false que você deve tratar, e como strchr() se relaciona com outras funções de string similares.

Sintaxe

strchr(string $haystack, string $needle, bool $before_needle = false): string|false

A função aceita três parâmetros:

• $haystack — a string onde a busca é realizada.
• $needle — a substring a ser procurada. Se contiver mais de um caractere, strchr() corresponde à substring inteira.
• $before_needle (opcional) — quando false (padrão), a parte da string a partir da correspondência em diante é retornada; quando true, a parte antes da correspondência é retornada. Adicionado no PHP 5.3.

Retorna a parte correspondente de $haystack como string, ou false se $needle não for encontrado.

Exemplo básico

strchr() localiza o primeiro "o" em "Hello World" e retorna o restante da string a partir desse caractere:

o World

Retornando a parte antes da correspondência

Passe true como terceiro argumento para obter tudo antes da primeira ocorrência:

<?php
$string = "Hello World";
$result = strchr($string, "o", true);
echo $result;
?>

Hell

Isso é útil para dividir uma string em um delimitador — por exemplo, obter a parte local de um endereço de e-mail pegando tudo antes de "@".

Tratando "não encontrado"

Quando o needle está ausente, strchr() retorna false, não uma string vazia. Como false é impresso como nada, um resultado não verificado pode silenciosamente produzir uma saída vazia, por isso teste-o explicitamente:

<?php
$result = strchr("Hello World", "z");
if ($result === false) {
    echo "Not found";
} else {
    echo $result;
}
?>

Not found

Use a comparação estrita ===: uma correspondência bem-sucedida pode ser a própria string "0", que == trataria como falso.

strchr() vs. funções relacionadas

• strstr() — strchr() é simplesmente um alias de strstr(); elas se comportam de forma idêntica. strstr() é o nome mais comumente usado.
• strpos() — retorna a posição inteira da primeira correspondência (ou false), em vez da substring correspondente. Use-o quando precisar de um índice para substr() ou outra lógica baseada em deslocamento.
• substr() — extrai uma parte de uma string por deslocamento numérico e comprimento, sem nenhuma busca envolvida.
• stristr() — a equivalente sem distinção entre maiúsculas e minúsculas de strstr()/strchr().

Resumo

strchr() encontra a primeira ocorrência de um needle em uma string e retorna o restante da string (ou, com $before_needle definido como true, a parte anterior a ela). Lembre-se de que é um alias de strstr(), que o needle pode ser uma substring com múltiplos caracteres, e que retorna false — o que você deve verificar com === — quando nada corresponde.

Prática