substr_count()

Introducción

La función substr_count() en PHP cuenta cuántas veces aparece una subcadena dentro de una cadena más grande. Devuelve un entero simple, lo que la hace útil para tareas como medir con qué frecuencia aparece una palabra en un bloque de texto, contar delimitadores antes de decidir cómo analizar un valor, o validar que una entrada contiene el número esperado de separadores.

Este capítulo cubre la sintaxis de la función, cómo los argumentos opcionales $offset y $length restringen la búsqueda, los dos comportamientos que más confunden a los desarrolladores (coincidencias superpuestas y distinción entre mayúsculas y minúsculas), y las situaciones prácticas en las que conviene usarla.

Sintaxis

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

La función devuelve el número de ocurrencias de $needle como un int.

Ejemplo básico

Aquí "is" aparece dos veces — una en "This" y otra en la palabra independiente "is" — por lo que la función devuelve 2.

Limitar la búsqueda con $offset y $length

El argumento $offset indica a substr_count() dónde empezar, y $length limita hasta dónde llega. Esto es útil cuando solo te interesa una parte de la cadena, como una sección de encabezado o un campo de ancho fijo.

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

En la primera llamada la búsqueda comienza en el índice 6, por lo que solo se cuenta el segundo "hello". En la segunda llamada la ventana es "bcabc" (5 caracteres a partir del índice 1), que contiene un único "abc" completo.

Si $offset y $length hacen que la búsqueda supere el final de la cadena, PHP lanza un ValueError. Mantén $offset + $length dentro de strlen($haystack).

Advertencia: las coincidencias superpuestas no se cuentan

substr_count() no cuenta las ocurrencias superpuestas. Después de encontrar una coincidencia, continúa desde el final de esa coincidencia, no desde el siguiente carácter.

<?php

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

Hay dos pares "aa" superpuestos en "aaa", pero la función solo cuenta el primero y luego continúa después de él. Si necesitas coincidencias superpuestas, usa una expresión regular con un lookahead mediante preg_match_all().

Advertencia: la búsqueda distingue mayúsculas de minúsculas

substr_count() realiza una comparación exacta, por lo que "Apple" y "apple" son subcadenas 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

Convertir la cadena a minúsculas con strtolower() antes de contar es la forma más sencilla de hacer la comparación sin distinción de mayúsculas y minúsculas.

Cuándo usar substr_count()

• Contar delimitadores — por ejemplo, verificar cuántas comas tiene una línea CSV antes de dividirla con explode().
• Frecuencia de palabras o tokens — medir con qué frecuencia aparece un término en un bloque de texto.
• Validación ligera — confirmar que un valor contiene el número esperado de separadores (por ejemplo, exactamente dos puntos en una cadena de versión).

Cuando necesitas la posición de una coincidencia en lugar de un recuento, usa strpos(); cuando quieres extraer parte de una cadena, usa substr().

Conclusión

substr_count() es una forma rápida y sencilla de contar ocurrencias de subcadenas y devolverlas como un entero. Recuerda sus dos comportamientos clave — omite las coincidencias superpuestas y distingue mayúsculas de minúsculas — y usa los argumentos $offset/$length para restringir la búsqueda cuando solo necesitas inspeccionar una parte de la cadena.

Práctica