PHP RFC: array_search_range()

• Version: 0.1 (Draft)
• Date: 2026-08-11
• Author: Sepehr Mahmoudi
• Email: sepehrphpr@gmail.com
• Target PHP Version: PHP 8.6
• Status: Draft
• Implementation: PR #YOUR_PR_NUMBER (Pending)

This RFC proposes a new core function named array_search_range().

The function searches for a value within a positional range of an existing array. It is intended for cases where an application needs to search only a part of an array, without first creating an intermediate array using array_slice().

function array_search_range(
    mixed $needle,
    array $haystack,
    int $offset = 0,
    ?int $length = null,
    bool $strict = false,
): int|string|false {}

array_search_range() searches for the first matching value in a selected range of an array and returns the original key of that value.

Like array_search(), it returns the actual key of the element. If no value matches, it returns false.

Currently, searching a portion of an array requires array_slice():

$range = array_slice($languages, 100, 50, true);
$key = array_search('PHP', $range, true);

This approach has two main drawbacks: 1. It creates an intermediate array, which consumes additional memory. 2. It requires two function calls instead of one.

The proposed function iterates over the original array directly, avoiding unnecessary memory allocation for an intermediate structure.

The value to search for.

The array in which the search is performed.

The zero-based positional offset at which searching begins.

• If $offset is negative, searching begins relative to the end of the array.
• If $offset is out of bounds (greater than array size), the function returns false.

The number of elements to inspect.

• When null, the function searches from $offset to the end of the array.
• If the requested length exceeds the remaining elements, the function searches until the end.
• If $length is 0, the function returns false.
• If $length is negative, the search excludes that number of elements from the end.

Whether to use strict comparison (=== vs ==).

The range is defined by positional order, not by the values of keys.

$array = [100 => 'alpha', 500 => 'target'];
// Search starts at the 2nd element (index 1), even if its key is 500
$key = array_search_range('target', $array, 1, 1, true);
var_dump($key); // int(500)

The function correctly preserves and returns the original keys regardless of whether they are integers or strings.

$mixedArray = ['a' => 'val1', 10 => 'val2', 'b' => 'target'];
$key = array_search_range('target', $mixedArray, 0, 3, true);
var_dump($key); // string(1) "b"

* If $offset is invalid or outside the array bounds, the function returns false. * This function does not throw exceptions for valid input ranges, maintaining consistency with array_slice().

$languages = ['HTML', 'CSS', 'JavaScript', 'PHP', 'Python'];
$key = array_search_range('PHP', $languages, 0, null, true);
var_dump($key); // int(3)

$items = ['zero', 'one', 'two', 'target', 'four', 'target'];
$key = array_search_range('target', $items, 2, 3, true);
var_dump($key); // int(3)

$users = ['u_101' => 'علی', 'u_103' => 'سپهر'];
$key = array_search_range('سپهر', $users, 0, null, true);
var_dump($key); // string(5) "u_103"

Compared to array_slice(), this function avoids creating a temporary HashTable. For an array of 100,000 elements, searching a range avoids allocating memory for the temporary slice, reducing GC pressure and CPU cycles required for array duplication.

The implementation focuses on direct HashTable iteration. The code will be submitted as a Pull Request to php-src. Full PHPT test coverage for edge cases including negative offsets, negative lengths, and mixed key types is included.

PHP 8.6.

• 0.1 — Initial draft by Sepehr Mahmoudi.