Descrição

strpos(string $haystack, string $needle, int $offset = 0): int|false

Encontra a posição numérica da primeira ocorrência de needle na string haystack.

Parâmetros

haystack

A string onde a substring será pesquisada.

needle

A substring a ser procurada.

Antes do PHP 8.0.0, se needle não for uma string, ela será convertida para um número inteiro e aplicada como o valor ordinal de um caractere. Este comportamento foi descontinuado a partir do PHP 7.3.0 e depender dele é altamente desaconselhado. Dependendo do comportamento pretendido, o parâmetro needle deve ser explicitamente convertido em string ou uma chamada explícita para chr() deve ser realizada.

offset

Se especificado, a pesquisa iniciará nessa posição de caractere contada a partir do início da string. Se for negativo, a pesquisa iniciará nessa posição de caractere contada a partir do final da string.

Valor Retornado

Retorna a posição em que a substring existe relativa ao início da string haystack (independente do offset). Observe também que as posições de string iniciam em 0, e não em 1.

Retorna false se a substring não for encontrada.

Aviso

Esta função pode retornar o valor booleano false, mas também pode retornar um valor não booleano que pode ser avaliado como false. Leia a seção sobre Booleanos para mais informações. Use o operador === para testar o valor retornado por esta função.

Erros/Exceções

Se offset for maior que o comprimento de haystack, um ValueError será lançado.

Registro de Alterações

Versão	Descrição
8.0.0	O parâmetro `needle` agora aceita uma string vazia.
8.0.0	Passar um int em `needle` não é mais suportado.
7.3.0	Passar um int em `needle` foi descontinuado.
7.1.0	Suporte a `offset` negativo foi adicionado.

Exemplos

Exemplo #1 Usando ===

<?php
$mystring = 'abc';
$findme   = 'a';
$pos = strpos($mystring, $findme);

// Observe o uso de ===. Simplesmente == não funcionaria como esperado
// porque o caractere 'a' fica na posição 0 (primeira) da string.
if ($pos === false) {
    echo "A string '$findme' não foi encontrada em '$mystring'";
} else {
    echo "A string '$findme' foi encontrada em '$mystring'";
    echo " e existe na posição $pos";
}
?>

Exemplo #2 Usando !==

<?php
$mystring = 'abc';
$findme   = 'a';
$pos = strpos($mystring, $findme);

// O operador !== também pode ser usado. Usar != não funcionaria como esperado
// porque a posição de 'a' é 0. A comparação (0 != false) é avaliada
// como falsa.
if ($pos !== false) {
     echo "A string '$findme' foi encontrada em '$mystring'";
         echo " e existe na posição $pos";
} else {
     echo "A string '$findme' não foi encontrada em '$mystring'";
}
?>

Exemplo #3 Usando um deslocamento

<?php
// Pode-se procurar um caractere, ignorando tudo antes do deslocamento
$newstring = 'abcdef abcdef';
$pos = strpos($newstring, 'a', 1); // $pos = 7, e não 0

echo $pos, PHP_EOL;
?>

Notas

Nota: Esta função é compatível com dados binários.

Veja Também

stripos() - Encontra a posição da primeira ocorrência de uma substring em uma string, de forma insensível a maiúsculas/minúsculas
str_contains() - Determina se uma string contém uma substring fornecida
str_ends_with() - Verifica se uma string termina com uma substring fornecida
str_starts_with() - Verifica se uma string começa com uma substring fornecida
strrpos() - Encontra a posição da última ocorrência de uma substring em uma string
strripos() - Encontra a posição da última ocorrência de uma substring em uma string, insensível a miúsculas/minúsculas
strstr() - Encontra a primeira ocorrência de uma string
strpbrk() - Procura na string por um dos caracteres de um conjunto
substr() - Retorna parte de uma string
preg_match() - Realiza uma correspondência com expressão regular