strncmp()

Introdução

A função strncmp() no PHP realiza uma comparação binária segura e sensível a maiúsculas/minúsculas dos primeiros N caracteres de duas strings. Em vez de comparar as strings inteiras, ela analisa apenas o trecho inicial que você especifica — o que a torna a ferramenta certa quando você se importa com um prefixo e não com o valor completo (por exemplo, verificar se uma URL começa com https, ou agrupar códigos que compartilham um cabeçalho comum).

Este artigo aborda a sintaxe de strncmp(), como interpretar seu valor de retorno, vários exemplos práticos e os erros comuns que costumam confundir as pessoas.

Sintaxe

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

strncmp() compara os primeiros $length caracteres de $string1 e $string2 byte a byte e retorna um inteiro:

A comparação é lexicográfica, baseada no valor de byte de cada caractere. Como as letras ASCII maiúsculas (A–Z, códigos 65–90) vêm antes das minúsculas (a–z, códigos 97–122), "Apple" é considerada menor que "apple". O número não nulo exato é a diferença do valor de byte do primeiro caractere divergente, mas você deve confiar apenas no seu sinal, não na sua magnitude.

Exemplo: comparando um prefixo

<?php

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

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

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

Mesmo que "Hello World" e "Hello" sejam diferentes no geral, seus primeiros 5 caracteres ("Hello") são idênticos, portanto strncmp() retorna 0 e a saída é:

The first 5 characters of Hello World are equal to the first 5 characters of Hello

Exemplo: verificando se uma string começa com um prefixo

Um uso clássico de strncmp() é testar a presença de um prefixo. Ao passar o comprimento do prefixo como $length, você compara apenas a parte do sujeito que o prefixo cobre:

<?php

$url = "https://www.w3docs.com";

if (strncmp($url, "https", 5) === 0) {
  echo "Secure URL";
} else {
  echo "Not secure";
}

Isso imprime Secure URL. No PHP 8.0+ a função dedicada str_starts_with() expressa a mesma intenção de forma mais clara, mas strncmp() continua sendo a escolha portável para versões mais antigas.

Exemplo: ela é sensível a maiúsculas/minúsculas

strncmp() distingue maiúsculas de minúsculas:

<?php

echo strncmp("PHP", "php", 3); // negative: 'P' (80) < 'p' (112)

Se você precisar ignorar a capitalização, use strncasecmp(), que realiza a mesma comparação limitada por comprimento sem sensibilidade a maiúsculas/minúsculas.

Erros comuns

• Apenas o sinal é significativo. Trate o resultado como "negativo / zero / positivo" e prefira === 0 quando quiser dizer "os prefixos coincidem". Não assuma que o valor é exatamente -1, 0 ou 1 — pode ser qualquer inteiro.
• $length maior que as strings é permitido. Se $length exceder o comprimento de qualquer uma das strings, strncmp() simplesmente compara até o fim da mais curta. strncmp("Hi", "Hi", 50) retorna 0.
• Um $length negativo lança um ValueError no PHP 8.0+ (e era tratado como 0 em versões mais antigas).
• É baseada em bytes, não compatível com multibytes. Para texto UTF-8, $length conta bytes, não caracteres, portanto um caractere multibyte pode ser dividido. Dados ASCII simples não são afetados.

Funções relacionadas

• strcmp() — compara duas strings completas, com distinção entre maiúsculas e minúsculas.
• strncasecmp() — como strncmp(), mas sem distinção entre maiúsculas e minúsculas.
• strcasecmp() — comparação sem distinção entre maiúsculas e minúsculas de strings completas.
• substr_compare() — compara strings a partir de um deslocamento escolhido.
• strpos() — encontra a posição de uma substring.

Conclusão

strncmp() compara apenas os primeiros N caracteres de duas strings, com distinção entre maiúsculas e minúsculas e de forma binária segura, retornando um número negativo, 0 ou um número positivo. Use-a quando precisar verificar um prefixo ou comparar uma parte inicial de comprimento fixo de duas strings — e lembre-se de verificar o sinal do resultado com === 0, < 0 ou > 0 em vez de um valor exato.

Prática