Sort.php

<?php

namespace Drupal\jsonapi\Query;

use Drupal\Core\Cache\CacheableMetadata;
use Drupal\Core\Http\Exception\CacheableBadRequestHttpException;

/**
 * Gathers information about the sort parameter.
 *
 * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
 *   class may change at any time and this will break any dependencies on it.
 *
 * @see https://www.drupal.org/project/drupal/issues/3032787
 * @see jsonapi.api.php
 */
class Sort {

  /**
   * The JSON:API sort key name.
   *
   * @var string
   */
  const KEY_NAME = 'sort';

  /**
   * The field key in the sort parameter: sort[lorem][<field>].
   *
   * @var string
   */
  const PATH_KEY = 'path';

  /**
   * The direction key in the sort parameter: sort[lorem][<direction>].
   *
   * @var string
   */
  const DIRECTION_KEY = 'direction';

  /**
   * The langcode key in the sort parameter: sort[lorem][<langcode>].
   *
   * @var string
   */
  const LANGUAGE_KEY = 'langcode';

  /**
   * The fields on which to sort.
   *
   * @var string
   */
  protected $fields;

  /**
   * Constructs a new Sort object.
   *
   * Takes an array of sort fields. Example:
   *   [
   *     [
   *       'path' => 'changed',
   *       'direction' => 'DESC',
   *     ],
   *     [
   *       'path' => 'title',
   *       'direction' => 'ASC',
   *       'langcode' => 'en-US',
   *     ],
   *   ]
   *
   * @param array $fields
   *   The entity query sort fields.
   */
  public function __construct(array $fields) {
    $this->fields = $fields;
  }

  /**
   * Gets the root condition group.
   */
  public function fields() {
    return $this->fields;
  }

  /**
   * Creates a Sort object from a query parameter.
   *
   * @param mixed $parameter
   *   The `sort` query parameter from the Symfony request object.
   *
   * @return self
   *   A Sort object with defaults.
   */
  public static function createFromQueryParameter($parameter) {
    if (empty($parameter)) {
      $cacheability = (new CacheableMetadata())
        ->addCacheContexts([
        'url.query_args:sort',
      ]);
      throw new CacheableBadRequestHttpException($cacheability, 'You need to provide a value for the sort parameter.');
    }

    // Expand a JSON:API compliant sort into a more expressive sort parameter.
    if (is_string($parameter)) {
      $parameter = static::expandFieldString($parameter);
    }

    // Expand any defaults into the sort array.
    $expanded = [];
    foreach ($parameter as $sort_index => $sort_item) {
      $expanded[$sort_index] = static::expandItem($sort_item);
    }
    return new static($expanded);
  }

  /**
   * Expands a simple string sort into a more expressive sort that we can use.
   *
   * @param string $fields
   *   The comma separated list of fields to expand into an array.
   *
   * @return array
   *   The expanded sort.
   */
  protected static function expandFieldString($fields) {
    return array_map(function ($field) {
      $sort = [];
      if ($field[0] == '-') {
        $sort[static::DIRECTION_KEY] = 'DESC';
        $sort[static::PATH_KEY] = substr($field, 1);
      }
      else {
        $sort[static::DIRECTION_KEY] = 'ASC';
        $sort[static::PATH_KEY] = $field;
      }
      return $sort;
    }, explode(',', $fields));
  }

  /**
   * Expands a sort item in case a shortcut was used.
   *
   * @param array $sort_item
   *   The raw sort item.
   *
   * @return array
   *   The expanded sort item.
   */
  protected static function expandItem(array $sort_item) {
    $cacheability = (new CacheableMetadata())
      ->addCacheContexts([
      'url.query_args:sort',
    ]);
    $defaults = [
      static::DIRECTION_KEY => 'ASC',
      static::LANGUAGE_KEY => NULL,
    ];
    if (!isset($sort_item[static::PATH_KEY])) {
      throw new CacheableBadRequestHttpException($cacheability, 'You need to provide a field name for the sort parameter.');
    }
    $expected_keys = [
      static::PATH_KEY,
      static::DIRECTION_KEY,
      static::LANGUAGE_KEY,
    ];
    $expanded = array_merge($defaults, $sort_item);

    // Verify correct sort keys.
    if (count(array_diff($expected_keys, array_keys($expanded))) > 0) {
      throw new CacheableBadRequestHttpException($cacheability, 'You have provided an invalid set of sort keys.');
    }
    return $expanded;
  }

}