PHP substr_count() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
String

Definition

In PHP, substr_count() counts how many times a piece of text appears in a string.

Matches do not overlap, and the search is case-sensitive.

Syntax

Call substr_count() with the values you need. Start with this line.

PHP
$total = substr_count($text, "php");
CallWhat it does
substr_count("banana", "a")Returns 3.
substr_count("aaaa", "aa")Returns 2 because matches do not overlap.
substr_count($text, "php", 5)Counts only after position 5.

An empty needle throws a ValueError in PHP 8. For counting single characters across a whole string, count_chars() is another option.

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

Parameters

ParameterDescription
haystackRequired. The string to search in.
needleRequired. The text to count. It must not be empty.
offsetOptional. Where to start searching. A negative value counts from the end. Default is 0.
lengthOptional. Maximum length to search after the offset.

Return Value

Return ValueDescription
intThe number of non-overlapping occurrences of needle.

PHP Examples

Example 1 — Count a Letter

How many times does "a" appear in "banana"?

PHP
<?php
$word = "banana";

echo substr_count($word, "a"), PHP_EOL;

How It Works

  1. Choose a needle. We look for "a".
  2. Scan the string. PHP finds it at positions 1, 3, and 5.
  3. Count matches. Three matches are found.
  4. Print. The function returns 3.

Example 2 — Matches Do Not Overlap

Once text is matched, PHP moves past it before searching again.

PHP
<?php
echo substr_count("aaaa", "aa"), PHP_EOL;
echo substr_count("Hello", "l"), PHP_EOL;
echo substr_count("Hello", "L"), PHP_EOL;

How It Works

  1. Non-overlapping. "aaaa" holds "aa" only twice, not three times.
  2. Normal count. "l" appears twice in "Hello".
  3. Case matters. "L" is a different character, so the count is 0.
  4. Tip. Lowercase the text first for a case-insensitive count.

Example 3 — Use Offset and Length

Limit the search to a part of the string.

PHP
<?php
$text = "php is fun, php is fast, php rocks";

echo substr_count($text, "php"), PHP_EOL;
echo substr_count($text, "php", 5), PHP_EOL;
echo substr_count($text, "php", 0, 11), PHP_EOL;

How It Works

  1. Whole string. "php" appears three times.
  2. Start at 5. The first "php" is skipped, leaving two matches.
  3. Limit to 11 characters. Only "php is fun," is searched.
  4. Result. That small part has one match.

Frequently Asked Questions

substr_count() counts how many times a substring appears in a string.
int substr_count(string $haystack, string $needle, int $offset = 0, ?int $length = null).
No. substr_count("aaaa", "aa") returns 2, not 3.
Yes. Use strtolower() on both strings first if you need to ignore case.
PHP 8 throws a ValueError. Always make sure the needle has at least one character.

Next: substr_replace()

substr_replace() replaces a part of a string with new text.

substr_replace() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful