PHP RFC: array_search_reange()

• Version: 0.1 (Draft)
• Date: 2026-08-11
• Author: Sepehr Mahmoudi
• Email: sepehrphpr@gmail.com
• Target PHP Version: PHP 8.6
• Status: Draft
• Implementation: Not yet available

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

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

The proposed function preserves the familiar return style of array_search() while adding parameters that define the reange in which the search is performed.

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

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

Like array_search(), the function returns:

• An int key when the matched element has an integer key.
• A string key when the matched element has a string key.
• false when no matching value exists in the selected reange.

The reange is defined by two parameters:

• $offset: The zero-based positional offset at which searching starts.
• $length: The number of elements to inspect after $offset.

PHP already provides array_search() for searching an entire array. When developers need to search only a portion of an array, they often combine array_slice() and array_search().

However, creating a sliced array solely for a single search operation is often unnecessary. The proposed function allows PHP to iterate over the requested reange of the original array directly, avoiding the allocation of an intermediate array.

A new function named array_search_reange() is added to PHP.

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

The function searches the original array in its normal iteration order. It begins at the positional offset specified by $offset and searches at most $length elements when a length is provided.

The value to search for.

The array in which the search is performed.

The zero-based positional offset at which searching begins. This refers to the position in the array's iteration order, defining the start of the reange.

The number of elements to inspect after applying $offset. When $length is null, the function searches from $offset to the end of the array.

When $strict is true, values are compared using strict comparison.

The reange is based on positions in the array's iteration order, not on key values.

$array = [
    100 => 'alpha',
    'php' => 'beta',
    500 => 'target',
];
 
// Searches for target in a reange starting at offset 2 (positional)
$key = array_search_reange('target', $array, 2, 1, true);
 
var_dump($key); // int(500)

The function returns the key from the original array, regardless of the reange selected.

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

This example searches only positions 2, 3, and 4.

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

$users = [
    'u_101' => 'علی',
    'u_102' => 'مینا',
    'u_103' => 'سپهر',
    'u_104' => 'رضا',
];
 
$key = array_search_reange('سپهر', $users, 1, 2, true);
var_dump($key); // string(5) "u_103"

The proposed API avoids creating an intermediate array when its only purpose is to be searched once. It makes the reange-limited search intention explicit.

This RFC is currently a draft. I plan to prepare a php-src implementation after the API design and parameter behavior receive feedback.

The implementation will include:

• The core implementation of array_search_reange().
• PHPT tests covering all cases (indexed, associative, strict/loose, negative

offsets, negative lengths, etc.).

• Benchmark results comparing this direct reange search with the

array_slice() pattern.

The implementation will be submitted as a pull request. It will not be merged until the RFC is accepted and the implementation is reviewed.

My roadmap for these features is as follows:

1. Finalize the design and implementation of ''array_search_reange()''.
2. Complete the discussion and merge the pull request into the PHP source.
3. Prepare the next feature: ''str_mask()''.

Regarding the future constant for array searching, it remains a separate discussion. I plan to design and document a constant for reange-limited searching only after array_search_reange() is stable and integrated.

The proposed target version for this feature is PHP 8.6.

• 0.1 — Initial draft by Sepehr Mahmoudi.