Deprecate not passing Criteria constants to orderBy()

[greg0ire]

I had the idea of doing this while trying to review doctrine/orm#11263

The signature of orderBy() is needlessly hard to understand for static
analysis. Also, if somebody makes a typo and writes "dsc", they will end
up with Criteria::ASC.

Let's also take this as an occasion to improve the documentation of Criteria::getOrderings()

[ThomasLandauer]

Just one quick question ("now or never"): Is Doctrine\Common\Collections\Criteria really the way to go or would it be better to create a dedicated class for those consts, higher in the namespace hierarchy, e.g. Doctrine\Order?

[greg0ire]

I think it might be better to have a class an enum indeed, but it should IMO stay in the collections namespace, I don't think we should create a dedicated namespace for that.

[ThomasLandauer]

So the future will be that strings will be forbidden in ->orderBy()? Then I'd suggest to go for a pure enum, and call it Order.

[greg0ire]

I think the future should be a string-backed enum. That way, we can create it in 2.2.x accept it in orderBy() and use it internally, deprecate not using it in 2.3.x and in 3.0.x use it in getOrderings as well.

<?php

enum Order: string
{
    case ASC = "ASC";
    case DESC = "DESC";
}

[greg0ire]

@ThomasLandauer here is how it could look like: #389