Master PHP’s strpos(): Syntax, Parameters, Return Values, and Common Pitfalls

Function Syntax

int strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )

Parameter Description

$haystack

: The string to search in (required). $needle: The character or substring to look for (required). $offset: Optional start position for the search, default is 0.

Return Values

If a match is found, the function returns the position of the first occurrence (0‑based).

If no match is found, it returns false.

Example Usage

Find a Single Character

$string = "Hello, World!";
$position = strpos($string, "o");
echo $position; // Outputs: 4

Find a Substring

$string = "Hello, World!";
$position = strpos($string, "World");
echo $position; // Outputs: 7

Search Starting from a Specific Offset

$string = "Hello, World!";
$position = strpos($string, "o", 5);
echo $position; // Outputs: 8

Check Whether a Match Exists

$string = "Hello, World!";
if (strpos($string, "o") !== false) {
    echo "Found!";
} else {
    echo "Not found!";
}

Important Notes

strpos() is case‑sensitive; use stripos() for case‑insensitive searches.

When the needle is at the start of the string, strpos() returns 0, so comparisons should use !== false rather than != false to avoid treating position 0 as false.

strpos() returns only the first match; to retrieve all matches, consider using a custom strpos_all() implementation.

Summary

The strpos() function is a fundamental PHP string‑handling tool for locating characters or substrings, returning the first match position or false if none is found; proper handling of parameters, return values, and edge cases ensures reliable usage.