strpos()

Introducción

La función strpos() en PHP encuentra la posición de la primera aparición de una subcadena dentro de otra cadena. Devuelve el índice basado en cero de esa aparición, o el boolean false si la subcadena no aparece nunca. Es una de las funciones de cadena más utilizadas en PHP — se recurre a ella cuando necesitas preguntar "¿contiene esta cadena ese texto, y dónde?".

Este capítulo cubre la sintaxis, la importantísima comprobación con === false, el parámetro $offset, la distinción entre mayúsculas y minúsculas, y las funciones relacionadas que debes conocer.

Sintaxis

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

Valor de retorno: la posición entera de la primera coincidencia (contando desde 0), o false cuando $needle no se encuentra.

Ejemplo básico

"World" comienza en el índice 6 de "Hello World" (la H está en el índice 0), por lo que la salida es:

Found 'World' in 'Hello World' at position 6

El problema con === false (léelo)

Este es el error más común con strpos(). Cuando la coincidencia está al inicio de la cadena, strpos() devuelve 0 — y 0 es falsy en PHP. Si compruebas el resultado con una verificación flexible como if (!strpos(...)) o if (strpos(...) == false), una coincidencia válida en la posición 0 se confunde con "no encontrado".

<?php

$haystack = "php is great";

// WRONG: 0 is treated as "not found"
if (strpos($haystack, "php")) {
  echo "loose: found\n";
} else {
  echo "loose: not found (WRONG!)\n";
}

// RIGHT: use the strict !== operator
if (strpos($haystack, "php") !== false) {
  echo "strict: found\n";
} else {
  echo "strict: not found\n";
}

Salida:

loose: not found (WRONG!)
strict: found

Compara siempre el resultado con el operador estricto !== (o ===). Esta es la regla de oro de strpos().

Búsqueda desde un offset

El tercer argumento le indica a strpos() dónde comenzar. Así es como se encuentran la segunda (y posteriores) apariciones de una subcadena — encontrar la primera y luego buscar de nuevo justo después de ella.

<?php

$text = "cat, dog, cat, bird";

$first  = strpos($text, "cat");        // 0
$second = strpos($text, "cat", $first + 1); // 10

echo "first: $first\n";
echo "second: $second\n";

Salida:

first: 0
second: 10

Un offset negativo inicia la búsqueda esa cantidad de caracteres desde el final de la cadena.

Distinción entre mayúsculas y minúsculas

strpos() distingue entre mayúsculas y minúsculas: "World" y "world" son subcadenas diferentes.

<?php

var_dump(strpos("Hello World", "world")); // bool(false)
var_dump(strpos("Hello World", "World")); // int(6)

Si necesitas una búsqueda sin distinción de mayúsculas y minúsculas, usa stripos() en su lugar — tiene la misma firma pero ignora las mayúsculas y minúsculas.

Solo comprobar "¿contiene X?"

Si solo te importa si existe una subcadena (no dónde), PHP 8.0+ ofrece la mucho más clara str_contains(), que devuelve un boolean simple y evita por completo el problema con === false:

<?php

// PHP 8.0+
var_dump(str_contains("Hello World", "World")); // bool(true)
var_dump(str_contains("Hello World", "world")); // bool(false)

Usa strpos() cuando necesites la posición; usa str_contains() cuando solo necesites una respuesta de sí/no.

Funciones relacionadas

• stripos() — versión sin distinción de mayúsculas y minúsculas de strpos().
• strrpos() — encuentra la última aparición en lugar de la primera.
• strstr() — devuelve la parte de la cadena desde la primera coincidencia en adelante.
• substr() — extrae una porción una vez que conoces la posición.
• str_replace() — reemplaza todas las apariciones de una subcadena.
• preg_match() — búsqueda basada en patrones cuando necesitas expresiones regulares.

Conclusión

strpos() devuelve la posición basada en cero de la primera aparición de una subcadena, o false si está ausente. Recuerda las dos reglas que más confunden a la gente: siempre comprueba el resultado con el estricto !== false, y recurre a stripos() o str_contains() cuando necesites coincidencia sin distinción de mayúsculas y minúsculas o una simple comprobación booleana.

Práctica