Everything
php
Learn Community Releases The PHP Project
Home » Project » Newsgroups » php.internals » [RFC] enum SortDirection »

[RFC] enum SortDirection

php.internals

Tim Düsterhus

182 days ago
Hi please consider this email as a formal request for comments on my modest proposal of adding a new `enum SortDirection` to PHP’s standard library. I have made the full proposal available on the World Wide Web at: https://wiki.php.net/rfc/sort_direction_enum Yours sincerely Tim Düsterhus

Bob Weinand

182 days ago
Hey Tim, On 2.3.2026 21:45:39, Tim Düsterhus wrote:
> Hi > > please consider this email as a formal request for comments on my > modest proposal of adding a new `enum SortDirection` to PHP’s standard > library. > > I have made the full proposal available on the World Wide Web at: > > https://wiki.php.net/rfc/sort_direction_enum > > Yours sincerely > Tim Düsterhus
That's a good idea, but I wouldn't introduce such class without some usages at least. I'd recommend considering immediately upgrading the proposed functions to use SortDirection and redefine the constants in terms of the enum. I.e. set const SORT_ASC = SortDirection::Ascending; - similar for others like the SCANDIR_SORT_DESCENDING etc.. This is a reasonable BC break, which is also trivially fixed by simply accepting int|SortDirection in existing functions. Thanks, Bob

Tim Düsterhus

182 days ago
Hi On 3/2/26 22:43, Bob Weinand wrote:
> That's a good idea, but I wouldn't introduce such class without some > usages at least. > > I'd recommend considering immediately upgrading the proposed functions > to use SortDirection and redefine the constants in terms of the enum. > > I.e. set const SORT_ASC = SortDirection::Ascending; - similar for others > like the SCANDIR_SORT_DESCENDING etc.. > > This is a reasonable BC break, which is also trivially fixed by simply > accepting int|SortDirection in existing functions.
A GitHub search for "language:PHP SORT_ASC" reveals that the existing constants are used in userland code for custom purposes (e.g. within a `switch()` statement). Redefining them to the enum would bring little value, but unnecessarily break them. See also https://wiki.php.net/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum for a precedent (specifically the Future Scope section there). As suggested in the “Future Scope” of the featured RFC widening the core functions to accept the enum and update the default value to the enum case can just happen without an RFC, since this should not be observable except by Reflection. I want to avoid a situation of explicitly listing *some* of the functions in the RFC, missing one and then later having a discussion of whether or not it requires a follow-up RFC to *also* adjust that missed one. Best regards Tim Düsterhus

Derick Rethans

182 days ago
On 2 March 2026 21:43:19 GMT, Bob Weinand <bobwei9@hotmail.com> wrote:
>Hey Tim, > >On 2.3.2026 21:45:39, Tim Düsterhus wrote: >> Hi >> >> please consider this email as a formal request for comments on my modest proposal of adding a new `enum SortDirection` to PHP’s standard library. >> >> I have made the full proposal available on the World Wide Web at: >> >> https://wiki.php.net/rfc/sort_direction_enum >> >> Yours sincerely >> Tim Düsterhus > > >That's a good idea, but I wouldn't introduce such class without some usages at least. > >I'd recommend considering immediately upgrading the proposed functions to use SortDirection and redefine the constants in terms of the enum. > >I.e. set const SORT_ASC = SortDirection::Ascending; - similar for others like the SCANDIR_SORT_DESCENDING etc.. > >This is a reasonable BC break, which is also trivially fixed by simply accepting int|SortDirection in existing functions.
If its a BC break, it can't go into a 8.× for something that isn't *necessary*. But I also don't see how accepting both int and this new enum for existing built-in functions is a BC break. Changing the existing constants to something else is probably not a good idea, as other user functions or libraries might have reused them. cheers Derick

Larry Garfield

182 days ago
On Mon, Mar 2, 2026, at 4:14 PM, Derick Rethans wrote:
> On 2 March 2026 21:43:19 GMT, Bob Weinand <bobwei9@hotmail.com> wrote: >>Hey Tim, >> >>On 2.3.2026 21:45:39, Tim Düsterhus wrote: >>> Hi >>> >>> please consider this email as a formal request for comments on my modest proposal of adding a new `enum SortDirection` to PHP’s standard library. >>> >>> I have made the full proposal available on the World Wide Web at: >>> >>> https://wiki.php.net/rfc/sort_direction_enum >>> >>> Yours sincerely >>> Tim Düsterhus >> >> >>That's a good idea, but I wouldn't introduce such class without some usages at least. >> >>I'd recommend considering immediately upgrading the proposed functions to use SortDirection and redefine the constants in terms of the enum. >> >>I.e. set const SORT_ASC = SortDirection::Ascending; - similar for others like the SCANDIR_SORT_DESCENDING etc.. >> >>This is a reasonable BC break, which is also trivially fixed by simply accepting int|SortDirection in existing functions. > > > > If its a BC break, it can't go into a 8.× for something that isn't *necessary*. > > But I also don't see how accepting both int and this new enum for > existing built-in functions is a BC break. > > Changing the existing constants to something else is probably not a > good idea, as other user functions or libraries might have reused them. > > cheers > Derick
I concur. I'd like to see the functions updated now in the RFC, so we get a sense of how many functions will be impacted. Not because I'm concerned about a widened type breaking anything, but more so readers can see the value this brings. The Yii DB layer (at least in v2, I haven't used v3 yet) used SORT_ASC/SORT_DESC for itself, so I agree that redefining those is unwise. Nit: Should we use Asc and Desc, for more compact code? Enums are great, but they can get verbose at times. :-) (SortDirection::Descending is 25 characters long, for what is ultimately a named boolean.) On the whole, though, I'm in favor. --Larry Garfield

Tim Düsterhus

181 days ago
Hi On 3/3/26 01:36, Larry Garfield wrote:
> I concur. I'd like to see the functions updated now in the RFC, so we get a sense of how many functions will be impacted. Not because I'm concerned about a widened type breaking anything, but more so readers can see the value this brings.
I see the main value in helping userland not to reinvent the wheel every time and to set some further precedent in including types for this kind of ubiquitous concept in the standard library. I don't want to commit to supporting the enum for every possible function in the standard library for the reasons I mentioned in my reply to Bob and also because some of the functions already have a very messy API signature where backfitting the enum is not exactly trivial.
> Nit: Should we use Asc and Desc, for more compact code?
I considered using the abbreviations, but then intentionally decided for the full names. Our naming policy (https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#acronyms) states:
> Abbreviations and acronyms as well as initialisms SHOULD be avoided wherever possible.
I don't believe that this enum is a case where it is warranted to diverge from the SHOULD. My rule of thumb here is that for an abbreviation to be acceptable, it must be the “more common form” of the term in question. As an example: I would say “I am sorting the list in descending order by name” or something like that. However when I am talking about the protocol that is commonly using TCP port 80 I would say “I am sending a HTTP request”, not “I am sending a request using the hypertext transfer protocol”. HTTP is the much much more commonly used term there and thus using the acronym is preferable. Also note how I used TCP instead of Transmission Control Protocol there. Doctrine, as listed in the references section of the RFC, has also opted to use the full names in their `Order` enum. Based on this Stack Overflow answer, using the full name also seems to be more common in the C# ecosystem: https://stackoverflow.com/a/22963304 Given it's also a strongly typed enum case rather than a “magic string” such as `'ASC'`, I expect IDE autocompletion to reduce much of the typing effort. Best regards Tim Düsterhus

Larry Garfield

172 days ago
On Tue, Mar 3, 2026, at 2:50 PM, Tim Düsterhus wrote:
> Hi > > On 3/3/26 01:36, Larry Garfield wrote: >> I concur. I'd like to see the functions updated now in the RFC, so we get a sense of how many functions will be impacted. Not because I'm concerned about a widened type breaking anything, but more so readers can see the value this brings. > > I see the main value in helping userland not to reinvent the wheel every > time and to set some further precedent in including types for this kind > of ubiquitous concept in the standard library. > > I don't want to commit to supporting the enum for every possible > function in the standard library for the reasons I mentioned in my reply > to Bob and also because some of the functions already have a very messy > API signature where backfitting the enum is not exactly trivial.
I'm not suggesting we update every single function in one RFC shot. But the RFC should include updating at least one or two so that the Enum is actually used. Otherwise, there's no real advantage to putting it in core rather than FIG. The reason to put it in core is so it can be used in core. So let's use it in core, even if not the full scope of eventual usage. --Larry Garfield

Tim Düsterhus

169 days ago
Hi Am 2026-03-13 19:11, schrieb Larry Garfield:
> Otherwise, there's no real advantage to putting it in core rather than > FIG. The reason to put it in core is so it can be used in core. So > let's use it in core, even if not the full scope of eventual usage.
I believe the RFC is sufficiently clear in how the enum can be useful for the PHP stdlib, listing some examples as future scope. And even if there would not (yet) be anything in the stdlib that could make use of it, I believe that asking users to install third party libraries with vendor-namespaces for a *data type* that is so broadly useful that it will likely be (transitively) required by every major framework is providing a good developer experience. Best regards Tim Düsterhus

Larry Garfield

169 days ago
On Mon, Mar 16, 2026, at 10:48 AM, Tim Düsterhus wrote:
> Hi > > Am 2026-03-13 19:11, schrieb Larry Garfield: >> Otherwise, there's no real advantage to putting it in core rather than >> FIG. The reason to put it in core is so it can be used in core. So >> let's use it in core, even if not the full scope of eventual usage. > > I believe the RFC is sufficiently clear in how the enum can be useful > for the PHP stdlib, listing some examples as future scope. And even if > there would not (yet) be anything in the stdlib that could make use of > it, I believe that asking users to install third party libraries with > vendor-namespaces for a *data type* that is so broadly useful that it > will likely be (transitively) required by every major framework is > providing a good developer experience. > > Best regards > Tim Düsterhus
To be clear, I'm not suggesting that FIG would be a better place for it. I am only saying that "let's add this... and then maybe later we'll get around to quietly using it without another RFC" is a poor message and poor expectation setting. When will I be able to use it for core functions? Which functions? How will I even know? What's the plan here other than "we can do that later quietly without telling anyone" (because vanishingly few PHP devs look at Internals PRs that have no RFC)? That's what is missing. --Larry Garfield

Tim Düsterhus

169 days ago
Hi Am 2026-03-16 17:55, schrieb Larry Garfield:
> […] Which functions? How will I even know? What's the plan here other > than "we can do that later quietly without telling anyone" (because > vanishingly few PHP devs look at Internals PRs that have no RFC)? > That's what is missing.
As with any other user-facing change, the changes to the function signatures would be listed in the NEWS file and the UPGRADING guide and would then be incorporated into the documentation, both in the function’s signature and the changelog that is available on every function page (e.g. “8.6.0 The $sorting_order parameter was widened to int|SortDirection”). I suppose that tools like Rector will also be able to suggest migrating from the old constants to the enum when that happens. Best regards Tim Düsterhus

Tim Düsterhus

169 days ago
Hi Am 2026-03-02 21:45, schrieb Tim Düsterhus:
> please consider this email as a formal request for comments on my > modest proposal of adding a new `enum SortDirection` to PHP’s standard > library. > > I have made the full proposal available on the World Wide Web at: > > https://wiki.php.net/rfc/sort_direction_enum
Two weeks have passed since the initial proposal of the RFC and no changes have been made. I plan to open voting later this week. Best regards Tim Düsterhus