0 follower

Final Class Yiisoft\Data\Reader\Sort

All Classes | Methods
InheritanceYiisoft\Data\Reader\Sort

Sort represents data sorting settings:

  • A config with a map of logical field => real fields along with their order. The config also contains the default order for each logical field.
  • Currently specified logical fields order such as field1 => asc, field2 => desc. Usually it is passed directly from the end user.

Logical fields are the ones user operates with. Real fields are the ones actually present in a data set. Such a mapping helps when you need to sort by a single logical field that, in fact, consists of multiple fields in the underlying data set. For example, you provide a user with a username which consists of first name and last name fields in the actual data set.

Based on the settings, the class can produce a criteria to be applied to {@see \Yiisoft\Data\Reader\SortableDataInterface} when getting the data that is a list of real fields along with their order directions.

There are two modes of forming a criteria available:

  • {@see \Yiisoft\Data\Reader\Sort::only()} ignores user-specified order for logical fields that have no configuration.
  • {@see \Yiisoft\Data\Reader\Sort::any()} uses user-specified logical field name and order directly for fields that have no configuration.

Psalm Types

Name Value
TOrder array<string, "asc"|"desc">
TSortFieldItem array<string, integer>
TConfigItem array{asc: \Yiisoft\Data\Reader\TSortFieldItem, desc: \Yiisoft\Data\Reader\TSortFieldItem, default: "asc"|"desc"}
TConfig array<string, \Yiisoft\Data\Reader\TConfigItem>
TUserConfigItem array{asc?: integer|"asc"|"desc"|array<string, integer|"asc"|"desc">, desc?: integer|"asc"|"desc"|array<string, integer|"asc"|"desc">, default?: "asc"|"desc"}
TUserConfig array<integer, string>|array<string, \Yiisoft\Data\Reader\TUserConfigItem>

Public Methods

Hide inherited methods

Method Description Defined By
any() Create a sort instance that uses logical field itself and direction provided when there is no configuration. Yiisoft\Data\Reader\Sort
getCriteria() Get a sorting criteria to be applied to {@see SortableDataInterface} when getting the data that is a list of real fields along with their order directions. Yiisoft\Data\Reader\Sort
getDefaultOrder() Get a default order for logical fields. Yiisoft\Data\Reader\Sort
getOrder() Get current logical fields order. Yiisoft\Data\Reader\Sort
getOrderAsString() Get an order string based on current logical fields order. Yiisoft\Data\Reader\Sort
hasFieldInConfig() Yiisoft\Data\Reader\Sort
only() Create a sort instance that ignores the current order for extra logical fields that have no configuration. Yiisoft\Data\Reader\Sort
withOrder() Return a new instance with a logical field order set. Yiisoft\Data\Reader\Sort
withOrderString() Get a new instance with a logical field order set from an order string. Yiisoft\Data\Reader\Sort
withoutDefaultSorting() Return a new instance without a default sorting set. Yiisoft\Data\Reader\Sort

Method Details

Hide inherited methods

any() public static method

Create a sort instance that uses logical field itself and direction provided when there is no configuration.

public static self any ( array $config = [] )
$config array

Logical fields config.

 

                public static function any(array $config = []): self
{
    return new self(false, $config);
}
getCriteria() public method

Get a sorting criteria to be applied to {@see SortableDataInterface} when getting the data that is a list of real fields along with their order directions.

public array getCriteria ( )
return array

Sorting criteria.

 

                public function getCriteria(): array
{
    $criteria = [];
    $config = $this->config;
    foreach ($this->currentOrder as $field => $direction) {
        if (array_key_exists($field, $config)) {
            $criteria = array_merge($criteria, $config[$field][$direction]);
            unset($config[$field]);
        } else {
            if ($this->ignoreExtraFields) {
                continue;
            }
            $criteria = array_merge($criteria, [$field => $direction === 'desc' ? SORT_DESC : SORT_ASC]);
        }
    }
    if ($this->withDefaultSorting) {
        foreach ($config as $fieldConfig) {
            $criteria += $fieldConfig[$fieldConfig['default']];
        }
    }
    return $criteria;
}
getDefaultOrder() public method

Get a default order for logical fields.

public TOrder getDefaultOrder ( )

                public function getDefaultOrder(): array
{
    return array_map(
        static fn(array $item) => $item['default'],
        $this->config,
    );
}
getOrder() public method

Get current logical fields order.

public array getOrder ( )
return array

Logical fields order.

 

                public function getOrder(): array
{
    return $this->currentOrder;
}
getOrderAsString() public method

Get an order string based on current logical fields order.

The string consists of comma-separated field names. If the name is prefixed with -, field order is descending. Otherwise, the order is ascending.

public string getOrderAsString ( )
return string

An order string.

 

                public function getOrderAsString(): string
{
    return OrderHelper::arrayToString($this->currentOrder);
}
hasFieldInConfig() public method

public boolean hasFieldInConfig ( string $name )
$name string

The field name.
return boolean

Whether the field is present in the config.

 

                public function hasFieldInConfig(string $name): bool
{
    return isset($this->config[$name]);
}
only() public static method

Create a sort instance that ignores the current order for extra logical fields that have no configuration.

public static self only ( array $config )
$config array

Logical fields config.

 

                public static function only(array $config): self
{
    return new self(true, $config);
}
withOrder() public method

Return a new instance with a logical field order set.

public self withOrder ( array $order )
$order array

A map with logical field names to order by as keys, direction as values.
return self

New instance.

 

                public function withOrder(array $order): self
{
    $new = clone $this;
    $new->currentOrder = $order;
    return $new;
}
withOrderString() public method

Get a new instance with a logical field order set from an order string.

The string consists of comma-separated field names. If the name is prefixed with -, field order is descending. Otherwise, the order is ascending.

public self withOrderString ( string $orderString )
$orderString string

Logical fields order as comma-separated string.
return self

New instance.

 

                public function withOrderString(string $orderString): self
{
    return $this->withOrder(
        OrderHelper::stringToArray($orderString),
    );
}
withoutDefaultSorting() public method

Return a new instance without a default sorting set.

public self withoutDefaultSorting ( )
return self

New instance.

 

                public function withoutDefaultSorting(): self
{
    $new = clone $this;
    $new->withDefaultSorting = false;
    return $new;
}