Class yii\data\Sort

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

Public Methods

Protected Methods

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.

public array getAttributeOrders ( $recalculate = false )
public void setAttributeOrders ( $attributeOrders, $validate = true )

$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 read-only property

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

public array getOrders ( $recalculate = false )

$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 = ','

$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

[
    'category',
    '-created_at'
]