substr_compare()

substr_compare() — Binary safe comparison of two strings from an offset, up to length characters.

Built-in function of PHP 8.5. The manual lists it as available in PHP 5, PHP 7, PHP 8. This page is the reference card: signature, parameters and return value, plus the changelog and the example the manual provides.

Signature

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

Parameters

ParameterTypeWhat it takes
$haystackstringThe main string being compared.
$needlestringThe secondary string being compared.
$offsetintThe start position for the comparison. If negative, it starts counting from the end of the string.
$length?intThe length of the comparison. The default value is the largest of the length of the needle compared to the length of haystack minus the offset.
$case_insensitiveboolIf case_insensitive is true, comparison is case insensitive.

Return value

Returns a value less than 0 if string1 is less than string2; a value greater than 0 if string1 is greater than string2, and 0 if they are equal. No particular meaning can be reliably inferred from the value aside from its sign.

Example

A runnable snippet:

echo substr_compare("abcde", "bc", 1, 2), PHP_EOL; // 0 echo substr_compare("abcde", "de", -2, 2), PHP_EOL; // 0 echo substr_compare("abcde", "bcg", 1, 2), PHP_EOL; // 0 echo substr_compare("abcde", "BC", 1, 2, true), PHP_EOL; // 0 echo substr_compare("abcde", "bc", 1, 3), PHP_EOL; // 1 echo substr_compare("abcde", "cd", 1, 2), PHP_EOL; // -1 echo substr_compare("abcde", "abc", 5, 1), PHP_EOL; // -1

Changelog

VersionChange
8.2.0This function is no longer guaranteed to return strlen($string1) - strlen($string2) when string lengths are not equal, but may now return -1 or 1 instead.
8.0.0Now throws a ValueError if offset is out of range or length is negative. Previously, an E_WARNING was raised and false was returned.
8.0.0length is nullable now.
7.2.18, 7.3.5offset may now be equal to the length of haystack.

See also

strncmp()

All PHP 8.5 built-in functions

Reference card built from the PHP manual page substr_compare() (PHP documentation, CC BY 3.0). The page is generated from the manual, so the wording of the parameter and return value text follows php.net.