strncasecmp()

Introdução

strncasecmp() compara os primeiros N caracteres de duas strings ignorando a diferença entre maiúsculas e minúsculas. Ela é o membro limitado e sem distinção de caixa da família de funções de comparação de strings do PHP:

• Ela ignora a caixa das letras, como strcasecmp() — A e a são tratados como iguais.
• Ela examina apenas os primeiros $length caracteres, como strncmp() — o restante de cada string é ignorado.

Em resumo: strncasecmp() está para strncmp() assim como strcasecmp() está para strcmp() — o mesmo trabalho, mas com a diferença de caixa eliminada antes da comparação. Esta página aborda a sintaxe, o que o valor de retorno realmente significa, vários exemplos executáveis e as armadilhas que costumam pegar as pessoas no código real.

Sintaxe

strncasecmp(string $string1, string $string2, int $length): int

A função retorna um inteiro, não um boolean — esta é a fonte mais comum de bugs (veja Gotchas).

O que significa o valor de retorno

O valor de retorno indica uma direção, não um verdadeiro/falso:

Apenas o sinal é garantido por contrato. Não confie na magnitude exata (versões mais antigas do PHP retornavam a diferença entre os primeiros bytes divergentes; o PHP 8 pode retornar -1/0/1). Teste sempre com < 0, === 0 ou > 0.

Exemplo básico

<?php

$string1 = "Hello World";
$string2 = "hello world";
$length  = 5;

$result = strncasecmp($string1, $string2, $length);

if ($result < 0) {
    echo "The first $length characters of $string1 are less than those of $string2";
} elseif ($result > 0) {
    echo "The first $length characters of $string1 are greater than those of $string2";
} else {
    echo "The first $length characters of $string1 are equal to those of $string2";
}

Os cinco primeiros caracteres são Hello e hello. Como a comparação ignora a caixa, eles são iguais, portanto a saída é:

The first 5 characters of Hello World are equal to those of hello world

Como $length altera o resultado

Somente os primeiros $length caracteres são inspecionados; tudo o que vem depois desse índice é invisível para a comparação. Isso torna strncasecmp() ideal para a correspondência de prefixos.

<?php

// "image/png" vs "IMAGE/JPEG"
var_dump(strncasecmp("image/png", "IMAGE/JPEG", 6) === 0); // compares "image/" — true
var_dump(strncasecmp("image/png", "IMAGE/JPEG", 9) === 0); // now "png" vs "JPE" differs — false

Saída:

bool(true)
bool(false)

Com um comprimento de 6, as duas strings compartilham o prefixo image/ (sem distinção de caixa), portanto são iguais. Ao ampliar a janela para 9, os sufixos diferentes (png e jpe) as tornam desiguais.

Uso prático: verificação de prefixo sem distinção de caixa

Uma necessidade comum no mundo real é saber se "esta string começa com X, independentemente da caixa?" — por exemplo, ao detectar o esquema de uma URL.

<?php

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

var_dump(startsWithIgnoreCase("HTTPS://w3docs.com", "https://")); // true
var_dump(startsWithIgnoreCase("ftp://files.example", "https://")); // false

Saída:

bool(true)
bool(false)

Passar strlen($prefix) como comprimento significa comparar exatamente o prefixo e nada além dele. No PHP 8 você também poderia usar str_starts_with(), mas ela diferencia maiúsculas de minúsculas — strncasecmp() continua sendo a escolha idiomática quando a caixa deve ser ignorada.

Gotchas

• Ela retorna um int, nunca um bool. Escrever if (strncasecmp($a, $b, 3)) entra no bloco quando as strings diferem (um valor diferente de zero é truthy) e o ignora quando elas são iguais (0 é falsy) — o oposto do que a maioria das pessoas pretende. Compare sempre de forma explícita: if (strncasecmp($a, $b, 3) === 0).
• Ela trabalha com bytes e não reconhece multibyte. $length conta bytes, e a normalização de caixa só funciona para ASCII (A–Z). Para texto acentuado ou não latino, use antes mb_strtolower() nos dois operandos, ou funções de comparação mb_*.
• Um $length maior que qualquer uma das strings não é problema. A comparação simplesmente termina no fim da string mais curta; não há leitura fora dos limites.
• Strings vazias são iguais para qualquer comprimento. strncasecmp("", "", 5) retorna 0.

Funções relacionadas

• strncmp() — a mesma comparação limitada, mas sensível a maiúsculas e minúsculas.
• strcasecmp() — comparação sem distinção de caixa da string inteira.
• strcmp() — comparação sensível a maiúsculas e minúsculas da string inteira.
• substr_compare() — compara a partir de um deslocamento arbitrário, com um sinalizador opcional para ignorar a caixa.
• strpos() — encontra a posição em que uma string ocorre dentro de outra.

Conclusão

strncasecmp() compara os primeiros $length caracteres de duas strings ignorando a caixa, retornando um número negativo, 0 ou um número positivo para indicar a ordem de classificação. Use-a quando precisar de uma correspondência de prefixo sem distinção de caixa ou quiser comparar apenas a parte inicial de duas strings. Lembre-se de que o resultado é um inteiro — teste sempre o sinal de forma explícita — e de que ela opera sobre bytes, portanto recorra às funções mb_* ao lidar com texto multibyte.

Prática