substr_count()

Introduction

La fonction substr_count() en PHP compte le nombre de fois qu'une sous-chaîne apparaît dans une chaîne plus grande. Elle retourne un entier simple, ce qui la rend pratique pour des tâches comme mesurer la fréquence d'un mot dans un bloc de texte, compter des délimiteurs avant de décider comment analyser une valeur, ou valider qu'une entrée contient le nombre attendu de séparateurs.

Ce chapitre couvre la syntaxe de la fonction, la manière dont les arguments optionnels $offset et $length restreignent la recherche, les deux comportements qui piègent le plus souvent les développeurs (correspondances chevauchantes et sensibilité à la casse), ainsi que les situations pratiques où vous l'utiliserez.

Syntaxe

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

La fonction retourne le nombre d'occurrences de $needle sous forme d'int.

Exemple de base

Ici, "is" apparaît deux fois — une fois dans "This" et une fois dans le mot isolé "is" — donc la fonction retourne 2.

Limiter la recherche avec $offset et $length

L'argument $offset indique à substr_count() où commencer, et $length limite la portée de la recherche. Cela est utile lorsque vous ne vous intéressez qu'à une partie d'une chaîne, comme une section d'en-tête ou un champ de largeur fixe.

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

Dans le premier appel, la recherche commence à l'index 6, donc seul le deuxième "hello" est compté. Dans le second appel, la fenêtre est "bcabc" (5 caractères à partir de l'index 1), qui contient un seul "abc" complet.

Si $offset et $length font dépasser la fin de la chaîne, PHP déclenche une ValueError. Assurez-vous que $offset + $length reste dans strlen($haystack).

Piège : les correspondances chevauchantes ne sont pas comptées

substr_count() ne compte pas les occurrences chevauchantes. Après avoir trouvé une correspondance, elle continue à partir de la fin de cette correspondance, et non du caractère suivant.

<?php

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

Il y a deux paires "aa" qui se chevauchent dans "aaa", mais la fonction ne compte que la première, puis reprend après celle-ci. Si vous avez besoin de correspondances chevauchantes, utilisez une expression régulière avec un lookahead via preg_match_all().

Piège : la recherche est sensible à la casse

substr_count() fait une correspondance exacte, donc "Apple" et "apple" sont des sous-chaînes différentes.

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

Mettre la chaîne source en minuscules avec strtolower() avant de compter est la manière la plus simple de rendre la comparaison insensible à la casse.

Quand utiliser substr_count()

• Compter des délimiteurs — par exemple, vérifier combien de virgules contient une ligne CSV avant de la diviser avec explode().
• Fréquence de mots ou de tokens — mesurer la fréquence d'apparition d'un terme dans un bloc de texte.
• Validation légère — confirmer qu'une valeur contient le nombre attendu de séparateurs (par ex., exactement deux points dans une chaîne de version).

Lorsque vous avez besoin de la position d'une correspondance plutôt que d'un comptage, utilisez strpos() ; lorsque vous souhaitez extraire une partie d'une chaîne, utilisez substr().

Conclusion

substr_count() est un moyen rapide et simple de compter les occurrences d'une sous-chaîne et de les retourner sous forme d'entier. Retenez ses deux comportements clés — elle ignore les correspondances chevauchantes et est sensible à la casse — et utilisez les arguments $offset/$length pour restreindre la recherche lorsque vous n'avez besoin d'inspecter qu'une partie d'une chaîne.

Pratique