(PHP 4, PHP 5, PHP 7, PHP 8)
strpos — Encontra a posição da primeira ocorrência de uma substring em uma string
Encontra a posição numérica da primeira ocorrência de
needle
na string haystack
.
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.
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.
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.
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.
|
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;
?>
Nota: Esta função é compatível com dados binários.