PHP substr_compare() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
String

Definition

In PHP, substr_compare() compares part of one string with another string.

It starts at an offset in the first string and returns 0 when both parts are equal.

Syntax

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

PHP
$result = substr_compare($text, "World", 6);
CallWhat it does
substr_compare("Hello World", "World", 6)Returns 0 because both parts match.
substr_compare("Hello World", "WORLD", 6, 5, true)Returns 0 because the check ignores case.
substr_compare("report.pdf", ".pdf", -4)Returns 0. A negative offset counts from the end.

A result of 0 means equal. A negative or positive number means the first part is smaller or larger. Always compare with === 0.

Library declarations
PHP
substr_compare(string $haystack, string $needle, int $offset, ?int $length = null, bool $case_insensitive = false): int

Parameters

ParameterDescription
haystackRequired. The main string to compare from.
needleRequired. The string to compare against.
offsetRequired. Where to start in haystack. A negative value counts from the end.
lengthOptional. How many characters to compare. Default compares to the end.
case_insensitiveOptional. If true, ignores letter case. Default is false.

Return Value

Return ValueDescription
intLess than 0 if the part of haystack is smaller, 0 if equal, and greater than 0 if larger.

PHP Examples

Example 1 — Compare From an Offset

Check whether the text starting at position 6 equals "World".

PHP
<?php
$text = "Hello World";

echo substr_compare($text, "World", 6), PHP_EOL;

How It Works

  1. Pick an offset. Position 6 is where "World" begins.
  2. Compare. PHP compares the rest of the string with the needle.
  3. Equal parts. Both are "World".
  4. Get 0. A result of 0 means they match.

Example 2 — Case-Sensitive vs Case-Insensitive

By default letter case matters. Turn on the last argument to ignore it.

PHP
<?php
$text = "Hello World";

var_dump(substr_compare($text, "WORLD", 6) === 0);
var_dump(substr_compare($text, "WORLD", 6, null, true) === 0);

How It Works

  1. Default mode. "World" and "WORLD" are different.
  2. Strict test. Comparing with === 0 gives false.
  3. Turn on case-insensitive mode. Pass true as the fifth argument.
  4. Use null for length. That means compare to the end of the string.

Example 3 — Check a File Extension

Use a negative offset to compare the last characters of a string.

PHP
<?php
$file = "report.PDF";

if (substr_compare($file, ".pdf", -4, 4, true) === 0) {
    echo "It is a PDF", PHP_EOL;
} else {
    echo "Not a PDF", PHP_EOL;
}

How It Works

  1. Negative offset. -4 starts four characters from the end.
  2. Compare four characters. The length is also 4.
  3. Ignore case. .PDF equals .pdf with the last flag on.
  4. Print the answer. The result is 0, so the first branch runs.

Frequently Asked Questions

substr_compare() compares a section of one string with another string. It returns 0 if they are equal.
int substr_compare(string $haystack, string $needle, int $offset, ?int $length = null, bool $case_insensitive = false).
Pass true as the fifth argument. Use null as the fourth argument if you do not want to set a length.
It counts from the end of haystack. An offset of -4 starts at the last four characters.
Yes. In PHP 8 it throws a ValueError if the offset is larger than the length of haystack or if length is negative.

Next: substr_count()

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

substr_count() 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