strpos()

Introduction

La fonction strpos() en PHP trouve la position de la première occurrence d'une sous-chaîne dans une autre chaîne. Elle retourne l'index à base zéro de cette occurrence, ou le boolean false si la sous-chaîne n'est pas trouvée. C'est l'une des fonctions de manipulation de chaînes les plus utilisées en PHP — vous y avez recours dès que vous avez besoin de savoir « cette chaîne contient-elle ce texte, et où ? ».

Ce chapitre couvre la syntaxe, la vérification indispensable === false, le paramètre $offset, la sensibilité à la casse et les fonctions associées à connaître.

Syntaxe

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

Valeur de retour : la position entière de la première correspondance (en comptant depuis 0), ou false si $needle n'est pas trouvé.

Exemple de base

"World" commence à l'index 6 dans "Hello World" (le H est à l'index 0), donc la sortie est :

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

Le piège === false (à lire absolument)

C'est le bug le plus courant avec strpos(). Lorsque la correspondance se trouve au début de la chaîne, strpos() retourne 0 — et 0 est considéré comme faux en PHP. Si vous testez le résultat avec une vérification souple comme if (!strpos(...)) ou if (strpos(...) == false), une correspondance valide à la position 0 sera prise pour « non trouvé ».

<?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";
}

Sortie :

loose: not found (WRONG!)
strict: found

Comparez toujours le résultat avec l'opérateur strict !== (ou ===). C'est la règle d'or de strpos().

Recherche à partir d'un offset

Le troisième argument indique à strpos() où commencer. C'est ainsi que vous trouvez la deuxième (et les suivantes) occurrences d'une sous-chaîne — trouvez la première, puis relancez la recherche juste après.

<?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";

Sortie :

first: 0
second: 10

Un offset négatif démarre la recherche à partir de la fin de la chaîne en comptant ce nombre de caractères.

Sensibilité à la casse

strpos() est sensible à la casse : "World" et "world" sont des sous-chaînes différentes.

<?php

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

Si vous avez besoin d'une recherche insensible à la casse, utilisez stripos() à la place — elle a la même signature mais ignore la casse des lettres.

Vérifier simplement « contient-il X ? »

Si vous voulez seulement savoir si une sous-chaîne existe (pas où), PHP 8.0+ propose la fonction bien plus lisible str_contains(), qui retourne un boolean et contourne entièrement le piège === false :

<?php

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

Utilisez strpos() quand vous avez besoin de la position ; utilisez str_contains() quand vous n'avez besoin que d'une réponse oui/non.

Fonctions associées

• stripos() — version insensible à la casse de strpos().
• strrpos() — trouve la dernière occurrence au lieu de la première.
• strstr() — retourne la partie de la chaîne à partir de la première correspondance.
• substr() — extrait une portion une fois que vous connaissez la position.
• str_replace() — remplace toutes les occurrences d'une sous-chaîne.
• preg_match() — recherche par motif quand vous avez besoin d'expressions régulières.

Conclusion

strpos() retourne la position à base zéro de la première occurrence d'une sous-chaîne, ou false si elle est absente. Retenez les deux règles qui piègent le plus souvent : testez toujours le résultat avec le strict !== false, et préférez stripos() ou str_contains() lorsque vous avez besoin d'une correspondance insensible à la casse ou d'un simple test boolean.

Pratique