substr_compare()

Introduzione

La funzione substr_compare() confronta una porzione di una stringa con un'altra stringa, partendo da un determinato offset. Funziona come confrontare una sottostringa di $main_str con $str — ma senza dover chiamare prima substr() per estrarre la sottostringa. Questo la rende il modo idiomatico e senza allocazioni per rispondere a domande come "questa stringa inizia con X?" o "questa stringa finisce con Y?" nelle versioni più vecchie di PHP.

Questo capitolo spiega i parametri, il significato del valore restituito e i pattern comuni (controllo del prefisso, controllo del suffisso, confronto case-insensitive) in cui substr_compare() eccelle.

Sintassi

substr_compare(
    string $haystack,
    string $needle,
    int $offset,
    ?int $length = null,
    bool $case_insensitive = false
): int

Nota: Il parametro $length è opzionale. In PHP 8+ è esplicitamente tipizzato come nullable (?int); passare null (o ometterlo) confronta fino alla fine di $haystack.

Valore restituito

substr_compare() restituisce un int:

• 0 — le porzioni confrontate sono uguali.
• un numero negativo — la porzione di $haystack è minore di $needle (viene prima nell'ordinamento).
• un numero positivo — la porzione di $haystack è maggiore di $needle (viene dopo nell'ordinamento).

Ciò che conta è il segno; la grandezza esatta è definita dall'implementazione e non deve essere considerata affidabile. Per verificare l'uguaglianza, confronta esplicitamente con 0: substr_compare(...) === 0.

Esempio di base

Qui confrontiamo i primi strlen($string2) (6) caratteri di "Hello World!" con "Hello!". Il sesto carattere è uno spazio (" ") nella prima stringa ma un punto esclamativo ("!") nella seconda; uno spazio (ASCII 32) viene prima di ! (ASCII 33), quindi la funzione restituisce un intero negativo (-1).

Verificare se una stringa inizia con un prefisso

Confrontare all'offset 0 con $length uguale alla lunghezza del prefisso è un modo efficace per testare se una stringa "inizia con" qualcosa:

<?php

function startsWith(string $haystack, string $prefix): bool
{
    return substr_compare($haystack, $prefix, 0, strlen($prefix)) === 0;
}

var_dump(startsWith("php-fpm", "php"));   // bool(true)
var_dump(startsWith("python", "php"));    // bool(false)

Su PHP 8.0+ puoi usare la funzione built-in str_starts_with() al suo posto. substr_compare() rimane utile su runtime più vecchi e quando hai bisogno anche della case-insensitivity.

Verificare se una stringa termina con un suffisso

Un offset negativo conta dalla fine della stringa, il che rende semplice il controllo del suffisso — non è necessario calcolare la posizione manualmente:

<?php

function endsWith(string $haystack, string $suffix): bool
{
    return substr_compare($haystack, $suffix, -strlen($suffix)) === 0;
}

var_dump(endsWith("report.pdf", ".pdf"));  // bool(true)
var_dump(endsWith("report.txt", ".pdf"));  // bool(false)

Confronto case-insensitive

Imposta il quinto argomento su true per ignorare le maiuscole:

<?php

$sensitive   = substr_compare("Hello", "hello", 0);
$insensitive = substr_compare("Hello", "hello", 0, null, true);

echo $sensitive;    // non-zero: 'H' and 'h' differ
echo PHP_EOL;
echo $insensitive;  // 0: equal when case is ignored

Avvertenze

• Offset fuori intervallo. Un $offset positivo maggiore della lunghezza di $haystack genera un ValueError in PHP 8+ (un avviso che restituisce false in PHP 7). Valida gli offset rispetto a strlen($haystack) quando provengono da input utente.
• $length maggiore di quanto rimane. Se $length supera i caratteri disponibili, vengono confrontati solo i caratteri disponibili — la funzione non genera errori, confronta semplicemente meno.
• Basato sui byte, non multibyte-aware. substr_compare() opera sui byte. Per testo UTF-8 dove un carattere può occupare più byte, gli offset e le lunghezze sono offset di byte, non di caratteri.

Funzioni correlate

• strcmp() — confronto binary-safe di due stringhe intere.
• strncmp() — confronta solo i primi n caratteri di due stringhe.
• strcasecmp() — confronto case-insensitive di due stringhe intere.
• substr() — estrae una porzione di una stringa.

Conclusione

substr_compare() confronta una porzione di una stringa con un'altra senza estrarla prima, il che la rende efficiente per i controlli di prefisso e suffisso. Ricorda di confrontare il risultato con 0 per verificare l'uguaglianza, usa un $offset negativo per i test "finisce con" e passa true come ultimo argomento quando le maiuscole devono essere ignorate.

Pratica