# Class yii\data\Sort

Inheritance | yii\data\Sort » yii\base\BaseObject
Implements | yii\base\Configurable
Available since version | 2.0
Source Code | https://github.com/yiisoft/yii2/blob/master/framework/data/Sort.php

Sort represents information relevant to sorting.

When data needs to be sorted according to one or several attributes, we can use Sort to represent the sorting information and generate appropriate hyperlinks that can lead to sort actions.

A typical usage example is as follows,

    public function actionIndex()
    {
        $sort = new Sort([
            'attributes' => [
                'age',
                'name' => [
                    'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
                    'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
                    'default' => SORT_DESC,
                    'label' => 'Name',
                ],
            ],
        ]);

        $models = Article::find()
            ->where(['status' => 1])
            ->orderBy($sort->orders)
            ->all();

        return $this->render('index', [
             'models' => $models,
             'sort' => $sort,
        ]);
    }

View:

    // display links leading to sort actions
    echo $sort->link('name') . ' | ' . $sort->link('age');

    foreach ($models as $model) {
        // display $model here
    }

In the above, we declare two $attributes that support sorting: `name` and `age`. We pass the sort information to the Article query so that the query results are sorted by the orders specified by the Sort object. In the view, we show two hyperlinks that can lead to pages with the data sorted by the corresponding attributes.

For more details and usage information on Sort, see the guide article on sorting.

## Public Properties

Hide inherited properties

Property | Type | Description | Defined By
--- | --- | --- | ---
$attributeOrders | array | Sort directions indexed by attribute names. Sort direction can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order. Note that the type of this property differs in getter and setter. See getAttributeOrders() and setAttributeOrders() for details. | yii\data\Sort
$attributes | array | List of attributes that are allowed to be sorted. | yii\data\Sort
$defaultOrder | array | The order that should be used when the current request does not specify any order. | yii\data\Sort
$enableMultiSort | boolean | Whether the sorting can be applied to multiple attributes simultaneously. | yii\data\Sort
$orders | array | The columns (keys) and their corresponding sort directions (values). This can be passed to yii\db\Query::orderBy() to construct a DB query. This property is read-only. | yii\data\Sort
$params | array | Parameters (name => value) that should be used to obtain the current sort directions and to create new sort URLs. | yii\data\Sort
$route | string | The route of the controller action for displaying the sorted contents. | yii\data\Sort
$separator | string | The character used to separate different attributes that need to be sorted by. | yii\data\Sort
$sortFlags | integer | Allow to control a value of the fourth parameter which will be passed to ArrayHelper::multisort() | yii\data\Sort
$sortParam | string | The name of the parameter that specifies which attributes to be sorted in which direction. | yii\data\Sort
$urlManager | yii\web\UrlManager | The URL manager used for creating sort URLs. | yii\data\Sort

## Public Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
__call() | Calls the named method which is not a class method. | yii\base\BaseObject
__construct() | Constructor. | yii\base\BaseObject
__get() | Returns the value of an object property. | yii\base\BaseObject
__isset() | Checks if a property is set, i.e. defined and not null. | yii\base\BaseObject
__set() | Sets value of an object property. | yii\base\BaseObject
__unset() | Sets an object property to null. | yii\base\BaseObject
canGetProperty() | Returns a value indicating whether a property can be read. | yii\base\BaseObject
canSetProperty() | Returns a value indicating whether a property can be set. | yii\base\BaseObject
className() | Returns the fully qualified name of this class. | yii\base\BaseObject
createSortParam() | Creates the sort variable for the specified attribute. | yii\data\Sort
createUrl() | Creates a URL for sorting the data by the specified attribute. | yii\data\Sort
getAttributeOrder() | Returns the sort direction of the specified attribute in the current request. | yii\data\Sort
getAttributeOrders() | Returns the currently requested sort information. | yii\data\Sort
getOrders() | Returns the columns and their corresponding sort directions. | yii\data\Sort
hasAttribute() | Returns a value indicating whether the sort definition supports sorting by the named attribute. | yii\data\Sort
hasMethod() | Returns a value indicating whether a method is defined. | yii\base\BaseObject
hasProperty() | Returns a value indicating whether a property is defined. | yii\base\BaseObject
init() | Normalizes the $attributes property. | yii\data\Sort
link() | Generates a hyperlink that links to the sort action to sort by the specified attribute. | yii\data\Sort
setAttributeOrders() | Sets up the currently sort information. | yii\data\Sort

## Protected Methods

Hide inherited methods

Method | Description | Defined By
--- | --- | ---
parseSortParam() | Parses the value of $sortParam into an array of sort attributes. | yii\data\Sort

## Property Details

$attributeOrders public property

Sort directions indexed by attribute names. Sort direction can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order. Note that the type of this property differs in getter and setter. See getAttributeOrders() and setAttributeOrders() for details.

public array $attributeOrders = null
$attributes public property

List of attributes that are allowed to be sorted. Its syntax can be described using the following example:

    [
        'age',
        'name' => [
            'asc' => ['first_name' => SORT_ASC, 'last_name' => SORT_ASC],
            'desc' => ['first_name' => SORT_DESC, 'last_name' => SORT_DESC],
            'default' => SORT_DESC,
            'label' => 'Name',
        ],
    ]

In the above, two attributes are declared: `age` and `name`. The `age` attribute is a simple attribute which is equivalent to the following:

    'age' => [
        'asc' => ['age' => SORT_ASC],
        'desc' => ['age' => SORT_DESC],
        'default' => SORT_ASC,
        'label' => Inflector::camel2words('age'),
    ]

Since 2.0.12 particular sort direction can be also specified as direct sort expression, like following:

    'name' => [
        'asc' => '[[last_name]] ASC NULLS FIRST', // PostgreSQL specific feature
        'desc' => '[[last_name]] DESC NULLS LAST',
    ]

The `name` attribute is a composite attribute:

- The `name` key represents the attribute name which will appear in the URLs leading to sort actions.
- The `asc` and `desc` elements specify how to sort by the attribute in ascending and descending orders, respectively. Their values represent the actual columns and the directions by which the data should be sorted by.
- The `default` element specifies by which direction the attribute should be sorted if it is not currently sorted (the default value is ascending order).
- The `label` element specifies what label should be used when calling link() to create a sort link. If not set, yii\helpers\Inflector::camel2words() will be called to get a label. Note that it will not be HTML-encoded.

Note that if the Sort object is already created, you can only use the full format to configure every attribute. Each attribute must include these elements: `asc` and `desc`.

public array $attributes = []
$defaultOrder public property

The order that should be used when the current request does not specify any order. The array keys are attribute names and the array values are the corresponding sort directions. For example,

    [
        'name' => SORT_ASC,
        'created_at' => SORT_DESC,
    ]

See also $attributeOrders.

public array $defaultOrder = null
$enableMultiSort public property

Whether the sorting can be applied to multiple attributes simultaneously. Defaults to `false`, which means each time the data can only be sorted by one attribute.

public boolean $enableMultiSort = false
$orders public property

The columns (keys) and their corresponding sort directions (values). This can be passed to yii\db\Query::orderBy() to construct a DB query. This property is read-only.

public array $orders = null
$params public property

Parameters (name => value) that should be used to obtain the current sort directions and to create new sort URLs. If not set, `$_GET` will be used instead.

In order to add hash to all links use `array_merge($_GET, ['#' => 'my-hash'])`.

The array element indexed by $sortParam is considered to be the current sort directions. If the element does not exist, the default order will be used.

See also:

- $sortParam
- $defaultOrder

public array $params = null
$route public property

The route of the controller action for displaying the sorted contents. If not set, it means using the currently requested route.

public string $route = null
$separator public property

The character used to separate different attributes that need to be sorted by.

public string $separator = ','
$sortFlags public property (available since version 2.0.33)

Allow to control a value of the fourth parameter which will be passed to ArrayHelper::multisort()

public integer $sortFlags = SORT_REGULAR
$sortParam public property

The name of the parameter that specifies which attributes to be sorted in which direction. Defaults to `sort`.

See also $params.

public string $sortParam = 'sort'
$urlManager public property

The URL manager used for creating sort URLs. If not set, the `urlManager` application component will be used.

public yii\web\UrlManager $urlManager = null

## Method Details

createSortParam() public method

Creates the sort variable for the specified attribute.

The newly created sort variable can be used to create a URL that will lead to sorting by the specified attribute.

public string createSortParam ( $attribute )
$attribute | string | The attribute name
return | string | The value of the sort variable
throws | yii\base\InvalidConfigException | if the specified attribute is not defined in $attributes

createUrl() public method

Creates a URL for sorting the data by the specified attribute.

This method will consider the current sorting status given by $attributeOrders. For example, if the current page already sorts the data by the specified attribute in ascending order, then the URL created will lead to a page that sorts the data by the specified attribute in descending order.

See also:

- $attributeOrders
- $params

public string createUrl ( $attribute, $absolute = false )
$attribute | string | The attribute name
$absolute | boolean | Whether to create an absolute URL. Defaults to `false`.
return | string | The URL for sorting. False if the attribute is invalid.
throws | yii\base\InvalidConfigException | if the attribute is unknown

getAttributeOrder() public method

Returns the sort direction of the specified attribute in the current request.

public integer|null getAttributeOrder ( $attribute )
$attribute | string | The attribute name
return | integer|null | Sort direction of the attribute. Can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order. Null is returned if the attribute is invalid or does not need to be sorted.

getAttributeOrders() public method

Returns the currently requested sort information.

public array getAttributeOrders ( $recalculate = false )
$recalculate | boolean | Whether to recalculate the sort directions
return | array | Sort directions indexed by attribute names. Sort direction can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order.

getOrders() public method

Returns the columns and their corresponding sort directions.

public array getOrders ( $recalculate = false )
$recalculate | boolean | Whether to recalculate the sort directions
return | array | The columns (keys) and their corresponding sort directions (values). This can be passed to yii\db\Query::orderBy() to construct a DB query.

hasAttribute() public method

Returns a value indicating whether the sort definition supports sorting by the named attribute.

public boolean hasAttribute ( $name )
$name | string | The attribute name
return | boolean | Whether the sort definition supports sorting by the named attribute.

init() public method

Normalizes the $attributes property.

public void init ( )

link() public method

Generates a hyperlink that links to the sort action to sort by the specified attribute.

Based on the sort direction, the CSS class of the generated hyperlink will be appended with "asc" or "desc".

public string link ( $attribute, $options = [] )
$attribute | string | The attribute name by which the data should be sorted by.
$options | array | Additional HTML attributes for the hyperlink tag. There is one special attribute `label` which will be used as the label of the hyperlink. If this is not set, the label defined in $attributes will be used. If no label is defined, yii\helpers\Inflector::camel2words() will be called to get a label. Note that it will not be HTML-encoded.
return | string | The generated hyperlink
throws | yii\base\InvalidConfigException | if the attribute is unknown

parseSortParam() protected method (available since version 2.0.12)

Parses the value of $sortParam into an array of sort attributes.

The format must be the attribute name only for ascending or the attribute name prefixed with `-` for descending.

For example the following return value will result in ascending sort by `category` and descending sort by `created_at`:

    [
        'category',
        '-created_at'
    ]

See also:

- $separator for the attribute name separator.
- $sortParam

protected array parseSortParam ( $param )
$param | string | The value of the $sortParam.
return | array | The valid sort attributes.

setAttributeOrders() public method (available since version 2.0.10)

Sets up the currently sort information.

public void setAttributeOrders ( $attributeOrders, $validate = true )
$attributeOrders | array|null | Sort directions indexed by attribute names. Sort direction can be either `SORT_ASC` for ascending order or `SORT_DESC` for descending order.
$validate | boolean | Whether to validate given attribute orders against $attributes and $enableMultiSort. If validation is enabled incorrect entries will be removed.