====== PHP RFC: Make the iterator_*() family accept all iterables ======
  * Version: 1.0
  * Date: 2022-06-21
  * Author: Tim Düsterhus, duesterhus@woltlab.com
  * Status: Implemented
  * Target Version: PHP 8.2
  * Implementation: https://github.com/php/php-src/commit/7ae7df5b4601f3f0ce45a27324fb9c6ebcbfc9ed
  * First Published at: http://wiki.php.net/rfc/iterator_xyz_accept_array


===== Introduction =====

PHP's <php>iterator_*()</php> family currently only accept <php>\Traversable</php>s (i.e. they reject plain <php>array</php>s). This is unnecessarily limiting.

Specifically this concerns the <php>iterator_to_array()</php> and <php>iterator_count()</php> functions. While each of them has an array-specific counterpart, the fact that one needs to choose either the array-specific variant or the everything-but-array variant makes writing code the deals with arbitrary <php>iterable</php>s unnecessarily verbose.

As an example: Allowing <php>iterator_to_array()</php> to take an array, makes it much easier to write functions accepting an <php>iterable</php> and processing it using <php>array_map()</php> et al:

<PHP>
function before(iterable $foo) {
    if (!is_array($foo)) {
        $foo = iterator_to_array($foo);
    }

    return array_map(strlen(...), $foo);
}
function after(iterable $foo) {
    $foo = iterator_to_array($foo);

    return array_map(strlen(...), $foo);
}
</PHP>

===== Proposal =====

The <php>$iterator</php> parameter of <php>iterator_to_array()</php> and <php>iterator_count()</php> should be widened from <php>\Traversable</php> to <php>iterable</php> (i.e. to <php>\Traversable|array</php>).

Specifically if this RFC is accepted the following shall hold:

==== iterator_to_array ====

<PHP>
iterator_to_array($array, true) == $array
iterator_to_array($array, false) == array_values($array)
</PHP>

==== iterator_count ====

<PHP>
iterator_count($array) == count($array)
</PHP>

==== iterator_apply ====

This function is **not** part of this proposal, because it is non-obvious how to define the behavior for <php>array</php>s, given that it does not pass the <php>Iterator</php> to the callback by default.

===== Backward Incompatible Changes =====

None, this is a purely type widening change.

===== Proposed PHP Version(s) =====

next PHP 8.x

===== RFC Impact =====

==== To SAPIs ====

none

==== To Existing Extensions ====

none

==== To Opcache ====

none

==== New Constants ====

none

==== php.ini Defaults ====

none

===== Open Issues =====

none

===== Unaffected PHP Functionality =====

Anything that isn't <php>iterator_to_array()</php> or <php>iterator_count()</php>.

===== Future Scope =====

none

===== Proposed Voting Choices =====

Each vote requires a 2/3 majority.

Voting opened 2022-07-05 14:30 UTC and closes on 2022-07-19 14:45 UTC.

<doodle title="iterator_to_array: Change the type of iterator_to_array()’s $iterator parameter from \Traversable to iterable?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>



<doodle title="iterator_count: Change the type of iterator_count()’s $iterator parameter from \Traversable to iterable?" auth="timwolla" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== Patches and Tests =====

https://github.com/php/php-src/pull/8819

===== Implementation =====

https://github.com/php/php-src/commit/7ae7df5b4601f3f0ce45a27324fb9c6ebcbfc9ed

===== References =====

  * Pre-RFC discussion: https://externals.io/message/117979
  * PoC implementation: https://github.com/php/php-src/pull/8819
  * Similar previous RFC that proposed adding **new** functions with an <php>iterable_*</php> prefix: https://wiki.php.net/rfc/iterable_to_array-and-iterable_count
  * Stack Overflow asking for <php>iterable_to_array()</php>: https://stackoverflow.com/q/44587973/782822

===== Rejected Features =====

none