phpstorm.dev

PHP ecosystem insights

PHP knowledge

Versioned PHP knowledge with primary sources and explicit verification dates.

Source checks through 2026-10-27 · 57 sources · This published snapshot is over 48 hours old.

Verified 2026-10-27 discussion Permanent entry

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

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.