[php-src] Issue #22344: Add array_flatten() to flatten multi‑dimensional arrays

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.