====== PHP RFC: enum SortDirection ======
  * Version: 1.0
  * Date: 2026-03-02
  * Author: Tim Düsterhus, timwolla@php.net
  * Status: Under Discussion
  * Implementation: tbd

===== Introduction =====

PHP’s standard library has no type-safe way to express sort direction. Today we use the integer constants <php>SORT_ASC</php> and <php>SORT_DESC</php> (which only work with <php>array_multisort()</php>), <php>SCANDIR_SORT_ASCENDING</php> and <php>SCANDIR_SORT_DESCENDING</php> (which only work with <php>scandir()</php>), bare <php>'ASC'</php> and <php>'DESC'</php> strings, <php>bool $ascending</php> flags, or entirely separate functions such as <php>sort()</php> vs <php>rsort()</php>.

Every major PHP framework and library ends up defining its own sort direction type. As an example, Doctrine introduced <php>\Doctrine\Common\Collections\Order</php> with <php>Ascending</php> and <php>Descending</php> cases as a replacement for its own now-deprecated string constants just two years ago.

This RFC proposes adding a single, always-available <php>SortDirection</php> enum to the global namespace:

<PHP>
<?php

enum SortDirection {
    case Ascending;
    case Descending;
}

?>
</PHP>

This is intentionally small. It is a universally useful, generic type representing a common use case that PHP itself, frameworks, and other userland code can all converge on.

===== Proposal =====

Add the following enum to ext/standard (in the global namespace):

<PHP>
<?php

enum SortDirection {
    case Ascending;
    case Descending;
}

?>
</PHP>

The enum is an unbacked enum, because there is no single obvious canonical serialization format. It is meant to represent a generic concept that is useful across a wide range of applications (e.g. SQL queries, query-string parameters in APIs, …) and these applications can trivially map the enum to an appropriate scalar value using <php>match()</php> statements.

==== Examples ====

SQL Query Builders:

<PHP>
<?php

$query->orderBy('created_at', SortDirection::Descending);

?>
</PHP>

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

The <php>SortDirection</php> class name in the global namespace is no longer available. A GitHub search for ''language:PHP /(enum|class) SortDirection/'' returns 178 results (both namespaced and unnamespaced).

Adding new symbols is not considered a BC break with regard to PHP’s policy, the name is the obvious choice and there is not a significant usage in the wild, making this an acceptable impact.

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

Next PHP 8.x (PHP 8.6).

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

==== To the Ecosystem ====

APIs using the enum will benefit from improved type safety and discoverability.

It is also trivially polyfillable and supports forward compatibility when allowing the enum in addition to string / integer values by means of a union type. As such we expect quick adoption by the ecosystem.

==== To Existing Extensions ====

Existing extensions may consider supporting the enum in addition to existing values in “sort direction” parameters (e.g. by means of a union type).

==== To SAPIs ====

None.

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

None.

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

  * Leveraging the enum in PHP’s standard library (e.g. for <php>scandir()</php>’s second parameter). This can happen without an RFC when it's just widening the type to an enum.

===== Voting Choices =====

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Implement the SortDirection enum as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

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

Trivial stub-change only, will happen when the RFC is accepted.

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====

  * Mailing List Discussion: https://news-web.php.net/php.internals/130226

  * PHP’s enum documentation using sort direction as a concept for the examples: https://www.php.net/manual/en/language.enumerations.examples.php
  * Doctrine commit adding the <php>Order</php> enum: https://github.com/doctrine/collections/commit/a288ea7d0af7763e05fc77fcc0c766f4b6f00fee

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

None.

===== Changelog =====

  * 2026-03-02: Initial version