Affected page

https://www.php.net/manual/en/function.grapheme-strrpos.php and https://www.php.net/manual/en/function.grapheme-strripos.php

Current issue

Both functions accept negative values for the $offset parameter, and the behavior is consistent with strrpos, mb_strrpos, and grapheme_strpos.
However, the manuals for grapheme_strrpos() and grapheme_strripos() do not mention that negative offsets are accepted and interpreted relative to the end of the string. This omission may lead to confusion or the assumption that negative offsets are unsupported.

Suggested improvement

Update the $offset parameter description in both pages to clarify how negative values are handled. For example:

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. The search is performed right to left, searching for the first occurrence of needle from the selected grapheme cluster.

Additional context (optional)

Environment tested:

• PHP 8.3.6
• ext-intl enabled
• ICU 74.2

Reproduction example:

<?php
// Pattern: 👪👨‍👩‍👦👨‍👩‍👧👨‍👩‍👧‍👦 repeated twice
$pattern =
    "\u{1F46A}" .                                   // 👪
    "\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F466}" . // 👨‍👩‍👦
    "\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}" . // 👨‍👩‍👧
    "\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}"; // 👨‍👩‍👧‍👦

$s = $pattern . $pattern; // 8 grapheme clusters total

$needle = "\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}"; // 👨‍👩‍👧

var_dump(grapheme_strrpos($s, $needle));       // int(6)
var_dump(grapheme_strrpos($s, $needle, -3));   // int(2)

var_dump(grapheme_strripos($s, $needle));      // int(6)
var_dump(grapheme_strripos($s, $needle, -3));  // int(2)

Note:
The phrase “right to left” comes from the strrpos documentation. For grapheme clusters, “backwards” might be a clearer description, but the proposed wording follows the established manual style for consistency.