Looks good, should we handle what i mentioned here: #18897 (comment)

(sharing the same field name on multiple sortmaps)

I don't think we need validation to prevent "overlapping" fields since each mapped key represents a complete, independent sorting strategy. This is actually a feature - it lets you create multiple sort options that include
the same fields in different combinations.

The concern about ambiguity is resolved by the design:

• No ambiguity exists because direct field sorting is disabled when sortMap is defined
• Each sort key (item1, item2) is self-contained and independent
• The question "In what direction should title be sorted?" doesn't arise because title itself is not a valid sort key

I don't think we need validation to prevent "overlapping" fields since each mapped key represents a complete, independent sorting strategy. This is actually a feature - it lets you create multiple sort options that include the same fields in different combinations.

The concern about ambiguity is resolved by the design:

* No ambiguity exists because direct field sorting is disabled when sortMap is defined

* Each sort key (item1, item2) is self-contained and independent

* The question "In what direction should title be sorted?" doesn't arise because title itself is not a valid sort key

Hmm, i'm probably not understanding it completely but

'sortMap' => [
  'item1' => ['title', 'created']
  'item2' => ['title', 'modified']
]

// sorting on both definitions: 
&item1=asc&item2=desc

Translates into the following statement right ?

SORT BY
   title ASC
   created ASC,
   title DESC,
   modified DESC 

&item1=asc&item2=desc

The paginatorhelper doesn't generate query strings like this. The direction can be specific only for 1 field, sort=item1&dir=asc

Imo we dont even need even sort asc/desc if we bind that into the key.

sort=title-asc
sort=title-desc

A flat list with all possible options

Imo we dont even need even sort asc/desc if we bind that into the key.

Yes that could be an additional enhancement, though what I would really like is the ability to do multi field/colum sort. The query string for it could be like sort[f1]=asc&sort[f2]=desc

@ADmad I think that kind of sort style is not very readable for the end user. This is something Drupal (facets/views) does and it is constantly a fight to get right for proper SEO

Maybe something like /products?sort=price:asc,rating:desc would be more friendly ?
or /products?sort=+price,-rating

With that said, we should of course be weary not to go back to Cake 1-2.x style query params. Good times... 🫠

Another thought that crosses my mind is then making sure that it is always returned in the same order to keep a canonical structure.

I think that kind of sort style is not very readable for the end user

The average non-techie user doesn't read/understand query string params :)

This is something Drupal (facets/views) does and it is constantly a fight to get right for proper SEO

I am not knowledgeable enough about how search engines deal with query string these days to be able to comment on this.

Maybe something like /products?sort=price:asc,rating:desc would be more friendly

This could work I guess.

BTW if for e.g. you have a search form with a multi-value field and using PRG you will get foo[] in the query string :)

Translates into the following statement right ?

Yes. You ask a bad question, you get a bad answer. The SQL you posted is syntactically correct, and is what I would expect to happen if all of those ordering clauses were combined.

A flat list with all possible options

This could work but we'll need to make PaginatorHelper aware of how to change direction. How would application code express that field-asc and field-desc are related and opposite directions?

With that said, we should of course be weary not to go back to Cake 1-2.x style query params. Good times... 🫠

No thank you 😄

I added a demo of combined sort & dir.
Wonder if that would work out better.

For me it looks quite complete.

What's Missing:

A way to specify default directions that can still be toggled. For example:

• Default: title ASC, created DESC
• When toggled: title DESC, created ASC

Potential Solution:

We could enhance the syntax to support default directions that flip together:

  'sortMap' => [
      // New syntax: use '@' prefix for toggleable fields with defaults
      'newest' => [
          '@title' => 'asc',     // Default asc, flips to desc
          '@created' => 'desc',  // Default desc, flips to asc
      ],
  ]

When user clicks the sort link:

• First click: title ASC, created DESC (defaults)
• Second click: title DESC, created ASC (inverted)

We could also invert this and make the @ signal that this is hardcoding the direction, as this might be more rare used.
Or, thinking about it (and in line of other languages, e.g. CSS),

  'newest' => [
      'title' => 'asc!',     // Only asc
      'created' => 'desc',  // Default desc, flips to asc
  ],

Use ! to signal that this is hardcoded in that direction.

For me it looks quite complete.

What's Missing:

A way to specify default directions that can still be toggled. For example:

* Default: title ASC, created DESC

* When toggled: title DESC, created ASC

Potential Solution:

We could enhance the syntax to support default directions that flip together:

  'sortMap' => [
      // New syntax: use '@' prefix for toggleable fields with defaults
      'newest' => [
          '@title' => 'asc',     // Default asc, flips to desc
          '@created' => 'desc',  // Default desc, flips to asc
      ],
  ]

When user clicks the sort link:

* First click: title ASC, created DESC (defaults)

* Second click: title DESC, created ASC (inverted)

We could also invert this and make the @ signal that this is hardcoding the direction, as this might be more rare used. Or, thinking about it (and in line of other languages, e.g. CSS),

  'newest' => [
      'title' => 'asc!',     // Only asc
      'created' => 'desc',  // Default desc, flips to asc
  ],

Use ! to signal that this is hardcoded in that direction.

I like the idea!

Could we have classes to define how a field should be ordered instead of a new syntax?

class OrderField 
{
  
    public function defaultDir(): ?string
    {
    }

    public function isFixedDir(): bool
    {
    }

    public function ormColumn(): array
}

As opt-in? I feel like as default this could become quite some overhead for apps to create.

or do you mean sth like

 namespace Cake\Datasource\Paging;

  class SortField 
  {
      protected string $field;
      protected ?string $defaultDirection;
      protected bool $locked;

      public function __construct(string $field, ?string $defaultDirection = null, bool $locked = false)
      {
          $this->field = $field;
          $this->defaultDirection = $defaultDirection;
          $this->locked = $locked;
      }

      public static function asc(string $field): self
      {
          return new self($field, 'asc', false);
      }

      public static function desc(string $field): self
      {
          return new self($field, 'desc', false);
      }

      public static function locked(string $field, string $direction): self
      {
          return new self($field, $direction, true);
      }

      public function getField(): string
      {
          return $this->field;
      }

      public function getDirection(string $requestedDirection, bool $directionSpecified): string
      {
          if ($this->locked) {
              return $this->defaultDirection;
          }

          if (!$directionSpecified && $this->defaultDirection) {
              return $this->defaultDirection;
          }

          return $requestedDirection;
      }

      public function isLocked(): bool
      {
          return $this->locked;
      }
  }

Usage Examples:

  'sortMap' => [
      'newest' => [
          SortField::desc('created'),  // Default desc, toggleable
          SortField::asc('title'),     // Default asc, toggleable
      ],
      'popular' => [
          SortField::locked('score', 'desc'),  // Always desc
          'author',  // Still support strings for BC
      ],
  ]

Yes, I like that. Maybe add an interface for it with methods getField and isLocked.

I'm not sure if the methods desc and asc are necessary, but the names could be clear, something like defaultDesc and defaultAsc.

We could maybe also create factory class for building the sortmap then. This would allow for a more strict and readable way for defining them.

$factory = SortMapFactory::create()
    ->field('title')
    ->field('created')
    ->field('rank', locked: true, default: 'desc')
    ->combo('newest', [
        SortField::desc('created'),
        SortField::asc('title'),
    ])
    ->combo('popular', [
        SortField::desc('score'),
        SortField::asc('comments_count'),
    ])
    ->combo('recently-updated', [
        SortField::desc('modified'),
        SortField::asc('title'),
    ])
    ->raw('alpha-group', [
        'group_name' => 'asc',
        'name' => 'asc',
    ]);

I added factory and SortField now with tests.
Also deprecated old sortableFields now.