PHP: rfc:array-sort-return-array

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Change behaviour of array sort functions to return a copy of the sorted array ======

  * Version: 0.1
  * Date: 2024-10-20
  * Author: Gina Peter Banyard <girgias@php.net>
  * Status: Withdrawn
  * Target Version: PHP 8.5
  * Implementation: TBD
  * First Published at: https://wiki.php.net/rfc/array-sort-return-array

===== Introduction =====

The PHP array sort functions take the array to sort as a by-reference array to sort the array in place.
However, since PHP 5.6 these function have only ever returned <php>true</php>.

Moreover, it would only return <php>false</php> (or <php>null</php>) prior to this version in case of a memory allocation failure.
This effectively means the return values of these functions are useless.
Similarly, <php>array_walk()</php>, <php>array_walk_recursive()</php>, and <php>shuffle()</php> have only ever returned <php>true</php>
(or in case of type errors <php>null</php> or <php>false</php> which are proper <php>TypeError</php>s as of PHP 8.0) since at least PHP 5.3.
One last array function that now only returns <php>true</php> since PHP 8.0 is <php>array_multisort()</php>,
when all warnings and false returns were converted to <php>ValueError</php>s and <php>TypeError</php>s.

This behaviour is annoying as it makes writing code in a functional way more cumbersome and tedious.
Indeed, when working with higher order functions (e.g. <php>array_map()</php>),
one cannot just use these functions as callbacks
and must instead wrap them in a closure which returns the sorted array.

===== Proposal =====

Change the return value of:

  * <php>sort()</php>
  * <php>rsort()</php>
  * <php>asort()</php>
  * <php>arsort()</php>
  * <php>ksort()</php>
  * <php>krsort()</php>
  * <php>natsort()</php>
  * <php>natcasesort()</php>
  * <php>usort()</php>
  * <php>uasort()</php>
  * <php>uksort()</php>
  * <php>array_multisort()</php>
  * <php>shuffle()</php>
  * <php>array_walk()</php>
  * <php>array_walk_recursive()</php>

from <php>true</php> to a copy of the <php>array</php> that is sorted, traversed, or shuffled.

This operation is effectively "for free" as we just increment the reference count of the sorted array by one.

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

Sorting an empty array and checking the return value of one of the <php>sort()</php> functions
would now be falsy rather than <php>true</php>.

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

The functions continue to take the first parameter by-reference and do the sorting in-place.

The sort methods from the SPL <php>ArrayObject</php> class are not affected by this change.

===== Version =====

Next minor version, PHP 8.5.

===== Vote =====

As per the voting RFC a yes/no vote with a 2/3 majority is needed for this proposal to be accepted.

Voting started on 2024-XX-XX and will end on 2024-XX-XX.
 
<doodle title="Accept Change behaviour of array sort functions to return a copy of the sorted array RFC?" auth="girgias" voteType="single" closed="true">
   * Yes
   * No
</doodle>

===== References =====

Internals discussion thread: https://externals.io/message/125809
Page Tools
