PHP RFC: enum SortDirection

• Version: 1.0
• Date: 2026-03-02
• Author: Tim Düsterhus, timwolla@php.net
• Status: Under Discussion
• Implementation: tbd

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

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

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

<?php
 
enum SortDirection {
    case Ascending;
    case Descending;
}
 
?>

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.

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

<?php
 
enum SortDirection {
    case Ascending;
    case Descending;
}
 
?>

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 match() statements.

SQL Query Builders:

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

The SortDirection 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.

Next PHP 8.x (PHP 8.6).

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.

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

None.

None.

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

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

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

After the RFC is implemented, this section should contain:

1. the version(s) it was merged into
2. a link to the git commit(s)
3. a link to the PHP manual entry for the feature

• 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 Order enum: https://github.com/doctrine/collections/commit/a288ea7d0af7763e05fc77fcc0c766f4b6f00fee

None.

• 2026-03-02: Initial version