PHP Manual: grapheme

Description

Procedural style

function grapheme_strpos(
    string $haystack,
    string $needle,
    int $offset = 0,
    string $locale = ""
): int|false

Find position (in grapheme units) of first occurrence of a string

Parameters

haystack

The string to look in. Must be valid UTF-8.

needle

The string to look for. Must be valid UTF-8.

offset

The optional offset parameter allows you to specify where in haystack to start searching as an offset in grapheme units (not bytes or characters). If the offset is negative, it is treated relative to the end of the string. The position returned is still relative to the beginning of haystack regardless of the value of offset.

locale

Locale to use. The locale affects how grapheme clusters are defined and how strings are compared. An empty string or null uses the default locale.

The locale identifier may include Unicode locale extension keys to control collation behavior. In particular, the ks key controls collation strength: for example, en_US-u-ks-identic enables identical-level comparison, which distinguishes Unicode variation selectors (such as emoji vs. text presentation) that are otherwise treated as equivalent. See Collator::setStrength() for the full mapping of ks values to collation strength levels.

Return Values

Returns the position as an integer. If needle is not found, grapheme_strpos() will return false.

Changelog

Version	Description
8.5.0	The optional parameter `locale` has been added.
7.1.0	Support for negative `offset`s has been added.

Examples

Example #1 grapheme_strpos() example

<?php

$char_a_ring_nfd = "a\xCC\x8A";  // 'LATIN SMALL LETTER A WITH RING ABOVE' (U+00E5) normalization form "D"
$char_o_diaeresis_nfd = "o\xCC\x88"; // 'LATIN SMALL LETTER O WITH DIAERESIS' (U+00F6) normalization form "D"

print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_nfd, $char_o_diaeresis_nfd);

?>

The above example will output:

Example #2 Using the ks-identic locale key to distinguish variation selectors

By default, Unicode variation selectors (U+FE0E text, U+FE0F emoji) are ignored during comparison. Using the ks-identic locale extension key enables identical-level collation, which treats them as distinct characters.

Note:
The locale parameter is available since PHP 8.5.0.

<?php

$textStyle  = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (text presentation selector)
$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (emoji presentation selector)

// Default locale: variation selectors are ignored, so the needle is found at position 0.
var_dump(grapheme_strpos($textStyle, $emojiStyle));

// With ks-identic: variation selectors are significant, so no match is found.
var_dump(grapheme_strpos($textStyle, $emojiStyle, 0, 'en_US-u-ks-identic'));

?>