[php-src] Issue #22344: Add array_flatten() to flatten multi‑dimensional arrays
| From: | Mahan-Iranfar | Date: | Tue, 16 Jun 2026 21:41:19 +0000 |
| Subject: | [php-src] Issue #22344: Add array_flatten() to flatten multi‑dimensional arrays | ||
| Groups: | php.bugs | ||
| Request: | Send a blank email to php-bugs+get-252204@lists.php.net to get a copy of this message | ||
Issue: https://github.com/php/php-src/issues/22344
Author: Mahan-Iranfar
### Description
### Description
PHP currently lacks a native function to flatten multi‑dimensional arrays into a single‑level
array. While **array_values()** reindexes the top‑level keys, it does not touch nested structures.
Developers are forced to write custom recursive logic or use cumbersome workarounds like
**array_reduce($array, 'array_merge', [])** (which fails for deeply nested arrays) or
**iterator_to_array(new RecursiveIteratorIterator(new RecursiveArrayIterator($array)), false)** –
neither of which is intuitive, performant, or discoverable.
### Solution
Add a new function:
function array_flatten(array $array, int $depth = 1, bool $preserve_keys = false):
array
- **$depth** – controls how many levels to flatten (default **1**, use **INF** to flatten
completely).
- **$preserve_keys** – when **true**, string keys are preserved (numeric keys are re‑indexed to
avoid collisions); when **false** (default), all keys are reset to sequential integers starting from
0.
### Examples:
```
$array = ['a' => 1, 'b' => ['c' => 2, 'd' =>
['e' => 3]]];
array_flatten($array); // [1, 2, ['e' => 3]]
array_flatten($array, 2); // [1, 2, 3]
array_flatten($array, INF); // [1, 2, 3]
array_flatten($array, INF, true); // ['a' => 1, 'c' => 2,
'e' => 3]
```
### Why This Belongs in the Core
1. Ubiquitous Need – Flattening arrays is one of the most common operations in data processing
(API responses, configuration merging, nested form inputs, etc.). Almost every major PHP framework
(Laravel, Yii, Symfony, October) provides a helper – a clear signal that the language itself
should offer a standardised, optimised implementation.
2. Performance & Correctness – A native implementation in C would be significantly faster than
any userland recursive function, especially for large or deeply nested arrays. It would also handle
edge cases (references, object values) consistently.
3. Modern Language Expectation – JavaScript (**Array.prototype.flat()**), Python
(**itertools.chain** or **list comprehensions**), Ruby (**flatten**), and even Rust (**flatten()**)
all provide a built‑in way to flatten arrays. PHP’s lack of such a basic array manipulation tool
makes it feel outdated and forces developers to leave the language to find third‑party solutions
– hurting the ecosystem’s competitiveness.
4. Ecosystem Consistency – A core function reduces code duplication, improves readability, and
encourages best practices across projects. It also makes PHP more approachable for newcomers coming
from other languages.
5. Alignment with PHP’s Current Direction – The recent “Four Pragmatic Directions” RFC and
numerous community discussions have emphasised adding practical array helpers to simplify everyday
code. **array_flatten()** fits perfectly into that vision – it is simple, well‑defined, and
solves a real pain point without introducing complexity.
### Counter‑arguments & Responses
- “You can implement it in userland in one line.”
While true for shallow arrays, userland implementations are slower, error‑prone for deep nesting,
and lack a standardised behaviour. Core functions exist precisely to provide reliable, optimised
solutions for common tasks.
- “The behaviour with keys is ambiguous.”
The proposed signature with **$preserve_keys** gives clear control, and the default behaviour
(**false**) is the most intuitive for most use cases. This mirrors the approach taken by other
languages.
### Impact & Modernisation
If PHP wants to remain a relevant, modern language for web development, it must offer the same
quality‑of‑life features that developers enjoy elsewhere. Adding array_flatten() is a small but
symbolic step that signals PHP is listening to its community and evolving with the times. Failing to
provide such a basic utility forces developers to reinvent the wheel for every project – a clear
sign of stagnation.
I strongly believe this function will see immediate widespread adoption and will significantly
improve the developer experience.