strpos()

Introduzione

La funzione strpos() in PHP trova la posizione della prima occorrenza di una sottostringa all'interno di un'altra stringa. Restituisce l'indice a base zero di tale occorrenza, oppure il boolean false se la sottostringa non è presente. È una delle funzioni per stringhe più utilizzate in PHP — la si usa ogni volta che si vuole chiedere "questa stringa contiene quel testo, e dove?".

Questo capitolo tratta la sintassi, il fondamentale controllo con === false, il parametro $offset, la distinzione tra maiuscole e minuscole, e le funzioni correlate che è utile conoscere.

Sintassi

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

Valore restituito: la posizione intera della prima corrispondenza (contando da 0), oppure false quando $needle non viene trovato.

Esempio di base

"World" inizia all'indice 6 in "Hello World" (la H si trova all'indice 0), quindi l'output è:

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

Il problema con === false (da leggere)

Questo è il bug più comune con strpos(). Quando la corrispondenza si trova all'inizio della stringa, strpos() restituisce 0 — e 0 è falso in PHP. Se si verifica il risultato con un controllo non stretto come if (!strpos(...)) o if (strpos(...) == false), una corrispondenza valida alla posizione 0 viene scambiata per "non trovato".

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

Output:

loose: not found (WRONG!)
strict: found

Confronta sempre il risultato con l'operatore stretto !== (o ===). Questa è la regola d'oro di strpos().

Ricerca a partire da un offset

Il terzo argomento indica a strpos() da dove iniziare. Questo è il modo per trovare la seconda (e successive) occorrenza di una sottostringa — si trova la prima, poi si cerca di nuovo partendo subito dopo.

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

Output:

first: 0
second: 10

Un offset negativo avvia la ricerca da quel numero di caratteri partendo dalla fine della stringa.

Distinzione tra maiuscole e minuscole

strpos() distingue tra maiuscole e minuscole: "World" e "world" sono needle diversi.

<?php

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

Se hai bisogno di una ricerca senza distinzione tra maiuscole e minuscole, usa stripos() — ha la stessa firma ma ignora le differenze tra maiuscole e minuscole.

Verificare semplicemente "contiene X?"

Se ti interessa solo sapere se una sottostringa esiste (non dove si trova), PHP 8.0+ offre la più chiara str_contains(), che restituisce un semplice boolean ed evita completamente il problema di === 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() quando hai bisogno della posizione; usa str_contains() quando ti basta una risposta sì/no.

Funzioni correlate

• stripos() — versione di strpos() senza distinzione tra maiuscole e minuscole.
• strrpos() — trova l'ultima occorrenza invece della prima.
• strstr() — restituisce la parte della stringa dalla prima corrispondenza in poi.
• substr() — estrae una porzione una volta nota la posizione.
• str_replace() — sostituisce tutte le occorrenze di una sottostringa.
• preg_match() — ricerca basata su pattern quando si usano le espressioni regolari.

Conclusione

strpos() restituisce la posizione a base zero della prima occorrenza di una sottostringa, oppure false se è assente. Ricorda le due regole che causano più problemi: verifica sempre il risultato con il rigoroso !== false, e usa stripos() o str_contains() quando hai bisogno di una ricerca senza distinzione tra maiuscole e minuscole o di un semplice controllo boolean.

Pratica