enum SortDirection View as Markdown

Introduction

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.

Proposal

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.

Examples

SQL Query Builders:

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

Backward Incompatible Changes

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.

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 scandir()’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:

Vote: Implement the SortDirection enum as outlined in the RFC? — Yes: 22 · No: 2 · Abstain: 2 (closed)

Patches and Tests

• https://github.com/php/php-src/pull/21501

Implementation

• https://github.com/php/php-src/commit/32c1931f18109655bc074dd5cda3248b838de636

References

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

• Voting Thread: https://news-web.php.net/php.internals/130395

• 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

Rejected Features

None.

Changelog

• 2026-03-02: Initial version