Class yii\data\Sort

Inheritanceyii\data\Sort » yii\base\BaseObject
Implementsyii\base\Configurable
Available since version2.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

PropertyTypeDescriptionDefined 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

MethodDescriptionDefined 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

MethodDescriptionDefined 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:

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.

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:

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:

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.