array_partition() function proposal
Under discussion; not accepted. The RFC page (version 0.1, dated 2026-10-25, author Ayoub Ezzini; edited
2026-10-26 at 14:35 UTC and 2026-10-27 at 10:31 and 16:22 UTC without a version change) lists its status as Under Discussion and proposes it for the next minor version (PHP 8.7).
The official RFC index lists it under discussion from 2026-10-25. The author opened the
[RFC] discussion thread at about 13:38 UTC on 25 October, after an earlier
karma-request thread that shaped the design. The voting thread is "tbd" and no
vote date is named. The implementation is php-src PR #24568.
Proposal
ext/standard would gain array_partition(array $array, callable $callback): array. The callback runs once per element,
in array order, and receives ($value, $key) like array_find(), array_find_key(), array_any() and array_all().
The result is always a list of two arrays: index 0 holds the elements for which the callback returned a truthy value,
index 1 holds the rest. Keys and relative order are preserved and the input is not modified, so
[$matching, $rest] = array_partition($array, $callback) always destructures.
The RFC defines index 0 as identical to array_filter($array, $callback, ARRAY_FILTER_USE_BOTH) and index 1 as the
array_diff_key() of the input and index 0. An empty input returns [[], []]. If the callback throws, the exception
propagates and no partial result is returned. Because the callback always gets two arguments, passing an internal
function with a fixed arity, such as 'is_string', throws ArgumentCountError. The RFC gives is_string(...) as a
form that also fails and an arrow-function wrapper as one that works. Since the 27 October edit it also lists
is_string(?) as working, labelled "partial function application (PHP 8.6+)"; the status of that feature was not
checked here.
Since the same edit the proposal section defines the behavior by a userland foreach implementation. The RFC says the
only observable difference is that the native function keeps by-reference elements of the input as references, like
array_filter(), and the loop does not.
Design decisions recorded in the RFC
- No
$modeparameter; it was removed after review in favor of thearray_find()callback signature. - Matching elements come first, as in the cited Laravel, Ruby, Kotlin, Rust and Haskell functions. A result keyed by
true/falsewas rejected because PHP casts boolean keys to integers, which would put the non-matching elements at index 0. - The parameter stays
$callbackrather than$predicate, so thecallback:named argument matches the other array functions. - It is a two-way split, not a general grouping function. The RFC calls the 2023
array_groupdraft (never voted) complementary.
Compatibility and limitations
The RFC's only listed backward-incompatible change is the global name: code that declares its own array_partition()
without a function_exists() guard would fail with "Cannot redeclare function". It notes earlier userland functions of
that name that split an array into N chunks. In old versions of a WordPress plugin the declaration was guarded, so a
call such as array_partition($posts, 3) would reach the native function and throw a TypeError. php-src issue
#14582 asked for the N-chunks meaning and was closed by its author in favor of array_chunk(). Only arrays are accepted; iterables are future scope. The RFC's benchmark puts the function on par with
array_filter() plus array_diff_key() and slightly slower than a hand-written loop. It was run on one machine by
the author and has not been reproduced here.
Discussion
The first reply came on 26 October at about 12:26 UTC (132928):
mickmackusa suggested folding the behavior into a general array_group() with an optional third parameter that seeds
empty groups in a chosen order, rather than adding array_partition() and later array_group(). The author
replied at about 14:34 UTC that seeded keys solve missing buckets
but not boolean-key casting: list destructuring matches by key, so seeding [true, false] still yields keys 1 and
0 and swaps the buckets, while string labels require the callback, the seed list and the destructuring keys to
agree (a typo silently creates an extra group). They kept the two-way function, citing array_find()/array_any()
alongside array_filter(), and said a future array_group() is not ruled out. The 14:35 UTC page edit adds this
argument to the "Why not a general grouping function?" section.
Tim Düsterhus reviewed the RFC at about 22:37 UTC and said he is in
favor. His points were editorial: a wiki-markup rendering error in the "An empty input" bullet; noting that a partial
function application placeholder such as is_string(?) should work in the arity example; linking the
destructuring coalesce RFC (declined, per his message) in the
grouping section; that the BC section's first paragraph understates the impact on function_exists()-guarded userland versions, whose behavior may
differ (though new symbols are not a BC break under policy); and extending the stub to a full userland polyfill, as the
array_find() RFC did. The author replied at about 10:36 UTC on 27 October that the
10:31 UTC page edit addresses all five points: the rendering fix, is_string(?) in the arity example (verified against
the implementation, per the author), links to the declined Destructuring Coalesce RFC, a rewritten first BC paragraph
(with or without a function_exists() guard, an existing userland array_partition() must be checked against the native
semantics) and the userland implementation described above. No vote date has been named.
At about 16:00 UTC Tim Düsterhus asked for an example that shows the
reference behavior. He said he is not sure he likes a function whose behavior cannot be replicated in userland, noted
that array_find() (he believes) drops references, and asked for more opinions. The author
replied at about 16:24 UTC. The 16:22 UTC edit adds a "By-reference
elements" example: writing through the result changes the input and vice versa, and a reference that is no longer
shared is copied as a plain value. The author said the functions that return part of their input (array_filter(),
array_diff_key(), array_slice(), array_values(), array_chunk()) keep references while array_find() and
array_map() drop them, and that keeping them means replacing the array_filter() + array_diff_key() idiom does not
change behavior. Dropping references would be a one-line change; reference handling is now the RFC's open issue, to be
settled before a vote. That classification of the other functions is the author's and was not checked here.
The thread had no replies at about 17:05 UTC on 25 October. The PR's code and tests were not checked. Until a
release, use array_filter() with array_diff_key() or a loop.
Related: pre-RFC coverage in the 24 October and 25 October digests.