[RFC] Follow-up on doctrine/collections Order enum

[greg0ire]

In doctrine/collections#389, I introduced a new enum: Order

What should we use it for inside the ORM?

• The OrderBy attribute: this is a clear use case where we should switch to that enum, since it has to do with collections
• QueryBuilder::orderBy() / addOrderBy(): this one is less clear to me… when you select several entities, you don't get a collection, but a list, right?
• DQL : I don't think we should allow it inside DQL, it's cumbersome
• Expr\OrderBy: I'm not sure we should do it here either.

@derrabus @SenseException any thoughts?

Cc @ThomasLandauer

[ThomasLandauer]

QueryBuilder::orderBy() / addOrderBy() was the place where I initially suggested to get rid of those strings (#11263) - so this is a must IMO :-)

[ThomasLandauer]

Anybody who was using ->orderBy('foo', Criteria::ASC) is kinda stuck now (after upgrading to doctrine/collections 2.2.0). PHPStan is going crazy with:

Fetching deprecated class constant ASC of class Doctrine\Common\Collections\Criteria: use Order::Ascending instead

But the enum isn't working yet:

Parameter #2 $order of method Doctrine\ORM\QueryBuilder::orderBy() expects string|null, Doctrine\Common\Collections\Order::Ascending given.

This can be overcome by using Order::Ascending->value (as you said in doctrine/collections#389 (comment)), but if the current situation is going to stay for longer than just a few days, then the deprecation message should be changed to:

... use Order::Ascending or Order::Ascending->value instead

[greg0ire]

@ThomasLandauer using Order::Ascending->value would solve the error, but there would still be a deprecation because ultimately, it's a string. We need to modify our public API to allow Order. Worse, it would mean users would have to first migrate to Order::Ascending->value, and then to Order::Ascending. 2 migrations instead of one.

@derrabus in doctrine/collections#389 (comment), I suggested we give the ORM a chance to upgrade, but I failed to make my point, so let me elaborate. What makes that upgrade so special that we should change the way we do things?

I think the main difference with other PRs where we add an API and immediately deprecate the other API is that we expect the users of doctrine/orm to use doctrine/collections's API when interacting with our own API, and don't support (yet) using the non-deprecated API. I suggest we remove the deprecation layer until we and probably the ODM folks (Cc @malarzm) figure out what changes to conduct in the ORM and the ODM. Or at least, the parts that could be referred to by our users, such as the Criteria::* constants.

[derrabus]

It's a bit unfortunate that the ORM uses constants from a different package in their public API. For ORM 2.19, we could add replacement constants to the ORM codebase. Supporting the Order enum directly is a feature I don't see for ORM 2.x anymore, tbh.

[derrabus]

Also, we have to be careful: Collections is not the only abstraction that we're dealing with here. When talking about the query builder, we're probably closer to the Persistence abstraction which also declares orderings as strings at the moment:

https://github.com/doctrine/persistence/blob/e7cf418cafe83a75f7a7096cc9fa890b201d28f1/src/Persistence/ObjectRepository.php#L42-L43

It would be a bit weird if the query builder and the repository used different abstractions for ordering stuff.

[NMe84]

The OrderBy attribute: this is a clear use case where we should switch to that enum, since it has to do with collections

I wouldn't switch, I'd support both for a while to give users time to adjust their code. Should be easy enough to accept string|Order as a parameter, right?

That said, the current situation leaves people with either a deprecation (which is very annoying in PhpUnit) or very ugly code in the form of something like this:

#[OrderBy(['id' => Order::Ascending->value])]

...where previously this much shorter and more readable version was usable:

#[OrderBy(['id' => Criteria::ASC])]

Supporting the Order enum directly is a feature I don't see for ORM 2.x anymore, tbh.

Then either the deprecation should go (because you can't fix the deprecation in an acceptable way in 2.x) or the functions requiring a string should also accept the enum, as I just suggested.

[curry684]

Supporting the Order enum directly is a feature I don't see for ORM 2.x anymore, tbh.

...thus forcing a double migration on all of us, migrating to Order::Ascending->value first in 2.x, and then breaking/deprecating all our code again when making the switch to 3?

[derrabus]

I mean, we could un-deprecate the constants, which basically means that Collections 3 would ship two constants it has no use for. I could live with that.

[curry684]

Preferably the constants would remain gone in 3 as you're otherwise going to be stuck with them sort of forever. I would just like a better migration path than we have now. For example (without really looking into the current code) we could consider introducing the Order enum as a static final class in 2.x, so Order::Ascending actually is a real string, and then in 3.x leave it as a real enum which is handled correctly as an enum everywhere. With something like that the final 2.x release would present a real upgrade path to 3 while being code-wise compatible.

This would interlock the major versions of Collections and ORM, but I doubt that's really a bad thing (ORM 3.x only works with major X or higher, ORM 2.x only works with major Y or lower).

Alternatively I don't really see why we wouldn't support the enums in 2.x, it can't be that much work to support both...?

[derrabus]

Preferably the constants would remain gone in 3 as you're otherwise going to be stuck with them sort of forever.

I think, I can live with the maintenance burden of two unused constants, really.

I would just like a better migration path than we have now.

Then don't use the constants for the query builder or metadata mapping. Use strings, as it is officially documented. The constants are part of the Collections package, meant for use with the Criteria class of that package. They just conveniently happen to match the values that the query builder and the mapping attributes accept.

The "migration path" that you're discussing is actually a workaround for people that have used those constants in an undocumented way, outside of their scope.

By keeping the constants around, we would give people who want to remain on ORM 2 (for what reason ever) the possibility keep everything as it is. Why's that a problem?

[curry684]

The "migration path" that you're discussing is actually a workaround for people that have used those constants in an undocumented way, outside of their scope.

Fair enough, I forgot about that perspective and indeed this will likely not affect that many people 😄

[malarzm]

until we and probably the ODM folks (Cc @malarzm) figure out what changes to conduct in the ORM and the ODM.

@greg0ire sorry for taking long to respond, I was on vacations :) You can take ODM out of equation for two reasons:

1. ODM's query builder is accepting 1 and -1 as well as asc and desc for sorting. Ints are used by MongoDB and are first-class citizens for us
2. ODM never got Selectable and therefore Criteria implemented (PersistentCollection doesn't have the matching method mongodb-odm#929 to have linked topics) 🙈

So feel free to do whatever is best for ORM here :)

[bobvandevijver]

The "migration path" that you're discussing is actually a workaround for people that have used those constants in an undocumented way, outside of their scope.

To chime in here: while it might be outside their scope, it is not undocumented. See https://www.doctrine-project.org/projects/doctrine-orm/en/3.0/reference/working-with-associations.html#filtering-collections, where the constant is used in the official documentation.

edit: after submitting this, I see it is actually a Criteria method, and not an ORM method... It is confusing, caused by all those untyped strings 😄 I would love to see either the enum to be supported, or an additional enum in the ORM namespace itself.

[VincentLanglet]

It's a bit unfortunate that the ORM uses constants from a different package in their public API. For ORM 2.19, we could add replacement constants to the ORM codebase.

Just my two cent, but I agree with this point.
doctrine/collections is not, at first sight, a Db-related library so it feel weird to me that doctrine/orm use constants/enums from doctrine/collections fro Db-related directive like "OrderBy".

So far I solved the "deprecated" issue by using again the string value 'ASC' or 'DESC',
but I would have expected a constant directly from doctrine/orm like Expr\Join::WITH,

Doctrine\ORM\Query\Expr\OrderBy::ASC;
Doctrine\ORM\Query\Expr\OrderBy::DESC;

[MartijnBUZ]

Hello, not a contributor, just someone who uses the package here (combined with Symfony) :)

I've just manually changed 200+ files from Criteria:: to Order::, because Criteria:: told me to do that, only to end up getting the errors as described above. This makes me a bit annoyed. After reading the replies I understand what the issue is (keeping things seperated).

I'd like to know what the long term solution is?

1. Should I just revert all my work and keep the deprecated code?
2. Should I update everything to the ->value notation (honestly, not really gonna do that, its ugly)
3. Should I replace everything with 'ASC' and 'DESC'? That feels a bit amateur-y.

I like using the const, as less strings is more better IMO, but Im not gonna do this job twice. Has any decision been made to just update the AddOrderBy method? Its one line extra ($order = $order instanceof Order ? $order->value : $order).

Could someone please shed some light on this?

[derrabus]

1. Should I just revert all my work and keep the deprecated code?

You can do that.

2. Should I update everything to the ->value notation (honestly, not really gonna do that, its ugly)

I would advise against that.

3. Should I replace everything with 'ASC' and 'DESC'?

That would be the usage as we've always documented it: https://www.doctrine-project.org/projects/doctrine-orm/en/3.2/reference/query-builder.html#high-level-api-methods

As I've written earlier, you've used constants from the collections package outside of their scope.

That feels a bit amateur-y.

I don't share that sentiment, tbh. But if you prefer constants, you can of course just create your own constants within your codebase and simply use those.

Has any decision been made to just update the AddOrderBy method?

Not likely to happen.

Its one line extra

… and a breaking change for anyone who overrides the query builder.

[VincentLanglet]

Doctrine\ORM\Query\Expr\OrderBy::ASC;
Doctrine\ORM\Query\Expr\OrderBy::DESC;

WDYT about adding these constants @greg0ire @derrabus ?

[derrabus]

Yes, we can do that, if that helps. Would it make sense to duplicate them on Doctrine\ORM\Mapping\OrderBy as well?

[MartijnBUZ]

The things with consts is that it makes programming a bit more robust. You type Order:: in your editor and you get two options, no room for error. With string i might've typed 'ASCENDING' and now I have weird errors. Yes, I know that this specific example is a bit silly, but its the philosophy behind it. It allowes for unittests to go over the ENUM_NAME::cases() to test behaviours etc.

At the very least I agree with the other replies that the deprecation notice could use a clearification, avoiding people to make the same mistake :) But in my case, I'll update it all to the strings (or my own consts), thanks for the reply :)