substr_count()

Introdução

A função substr_count() no PHP conta quantas vezes uma substring aparece dentro de uma string maior. Ela retorna um número inteiro simples, o que a torna útil para tarefas como medir a frequência de uma palavra em um texto, contar delimitadores antes de decidir como analisar um valor, ou validar que uma entrada contém o número esperado de separadores.

Este capítulo aborda a sintaxe da função, como os argumentos opcionais $offset e $length restringem a busca, os dois comportamentos que mais confundem as pessoas (correspondências sobrepostas e sensibilidade a maiúsculas/minúsculas) e as situações práticas em que você a utilizaria.

Sintaxe

substr_count(string $haystack, string $needle, int $offset = 0, ?int $length = null): int

A função retorna o número de ocorrências de $needle como um int.

Exemplo básico

Aqui "is" aparece duas vezes — uma em "This" e outra na palavra isolada "is" — portanto a função retorna 2.

Limitando a busca com $offset e $length

O argumento $offset informa a substr_count() onde começar, e $length limita até onde ela vai. Isso é útil quando você se preocupa apenas com parte de uma string, como uma seção de cabeçalho ou um campo de largura fixa.

<?php

$text = "hello world hello";

// Start searching after the first word.
echo substr_count($text, "hello", 6), "\n"; // 1

// Search only the first 5 characters, starting at index 1.
echo substr_count("abcabcabc", "abc", 1, 5), "\n"; // 1

Na primeira chamada, a busca começa no índice 6, portanto apenas o segundo "hello" é contado. Na segunda chamada, a janela é "bcabc" (5 caracteres começando no índice 1), que contém um único "abc" completo.

Se $offset e $length ultrapassarem o final da string, o PHP lança um ValueError. Mantenha $offset + $length dentro de strlen($haystack).

Atenção: correspondências sobrepostas não são contadas

substr_count() não conta ocorrências sobrepostas. Após encontrar uma correspondência, ela continua a partir do final dessa correspondência, não do próximo caractere.

<?php

echo substr_count("aaa", "aa"); // 1, not 2

Existem dois pares sobrepostos de "aa" em "aaa", mas a função conta apenas o primeiro e continua depois dele. Se você precisar de correspondências sobrepostas, use uma expressão regular com lookahead via preg_match_all().

Atenção: a busca diferencia maiúsculas de minúsculas

substr_count() faz correspondência exata, portanto "Apple" e "apple" são substrings diferentes.

<?php

$text = "Apple apple APPLE";

echo substr_count($text, "apple"), "\n"; // 1

// Normalize the case first for a case-insensitive count.
echo substr_count(strtolower($text), "apple"), "\n"; // 3

Converter a string para minúsculas com strtolower() antes de contar é a forma mais simples de tornar a comparação insensível a maiúsculas/minúsculas.

Quando usar substr_count()

• Contagem de delimitadores — por exemplo, verificar quantas vírgulas uma linha CSV possui antes de dividi-la com explode().
• Frequência de palavras ou tokens — medir com que frequência um termo aparece em um bloco de texto.
• Validação simples — confirmar que um valor contém o número esperado de separadores (por exemplo, exatamente dois pontos em uma string de versão).

Quando você precisa da posição de uma correspondência em vez de uma contagem, use strpos(); quando quiser extrair parte de uma string, use substr().

Conclusão

substr_count() é uma forma rápida e simples de contar ocorrências de substrings e retorná-las como um número inteiro. Lembre-se dos dois comportamentos principais — ela ignora correspondências sobrepostas e diferencia maiúsculas de minúsculas — e use os argumentos $offset/$length para restringir a busca quando precisar inspecionar apenas parte de uma string.

Prática