Sort

API reference › yii › data › Sort

class	yii\data\Sort
Extends	yii\base\BaseObject
Implements	yii\base\Configurable
Since	2.0
Source	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.

Properties

Property	Type	Description	Defined by
$attributeOrders	array|null	Sort directions indexed by attribute names.	Sort
$attributes	array	List of attributes that are allowed to be sorted. Default: [].	Sort
$defaultOrder	array|null	The order that should be used when the current request does not specify any order. Default: null.	Sort
$enableMultiSort	bool	Whether the sorting can be applied to multiple attributes simultaneously. Default: false.	Sort
$modelClass	string|null	The name of the Model-based class used by the link() method to retrieve attributes’ labels. Default: null. Available since 2.0.49.	Sort
$orders read-only	array	The columns (keys) and their corresponding sort directions (values).	Sort
$params	array|null	Parameters (name => value) that should be used to obtain the current sort directions and to create new sort URLs. Default: null.	Sort
$route	string|null	The route of the controller action for displaying the sorted contents. Default: null.	Sort
$separator	string	The character used to separate different attributes that need to be sorted by. Default: ','.	Sort
$sortFlags	int	Allow to control a value of the fourth parameter which will be passed to ArrayHelper::multisort() Default: SORT_REGULAR. Available since 2.0.33.	Sort
$sortParam	string	The name of the parameter that specifies which attributes to be sorted in which direction. Default: 'sort'.	Sort
$urlManager	yii\web\UrlManager|null	The URL manager used for creating sort URLs. Default: null.	Sort

Methods

Method	Description	Defined by
__construct()	Constructor.	yii\base\BaseObject
__call()	Calls the named method which is not a class method.	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() static	Returns the fully qualified name of this class.	yii\base\BaseObject
createSortParam()	Creates the sort variable for the specified attribute.	Sort
createUrl()	Creates a URL for sorting the data by the specified attribute.	Sort
getAttributeOrder()	Returns the sort direction of the specified attribute in the current request.	Sort
getAttributeOrders()	Returns the currently requested sort information.	Sort
getOrders()	Returns the columns and their corresponding sort directions.	Sort
hasAttribute()	Returns a value indicating whether the sort definition supports sorting by the named attribute.	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.	Sort
link()	Generates a hyperlink that links to the sort action to sort by the specified attribute.	Sort
setAttributeOrders()	Sets up the currently sort information.	Sort
parseSortParam() protected	Parses the value of $sortParam into an array of sort attributes.	Sort
resolveRoute() protected	Resolves the target route from $route, the active controller, or Application::$requestedRoute.	Sort

Property details

$attributeOrders

public array|null $attributeOrders

Sort directions indexed by attribute names.

Sort direction can be either SORT_ASC for ascending order or SORT_DESC for descending order.

$attributes

public array $attributes = []

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, 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.

$defaultOrder

public array|null $defaultOrder = null

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,
]

$enableMultiSort

public bool $enableMultiSort = false

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.

$modelClass

public string|null $modelClass = null

The name of the Model-based class used by the link() method to retrieve attributes’ labels.

See link() method for details.

Since

2.0.49

$orders

public array $orders

The columns (keys) and their corresponding sort directions (values).

This can be passed to Query::orderBy() to construct a DB query.

Access

Read-only (virtual property).

$params

public array|null $params = null

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.

$route

public string|null $route = null

The route of the controller action for displaying the sorted contents.

If not set, it means using the currently requested route.

$sortParam

public string $sortParam = 'sort'

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

Defaults to sort.

$urlManager

public yii\web\UrlManager|null $urlManager = null

The URL manager used for creating sort URLs.

If not set, the urlManager application component will be used.

Method details

createSortParam()

public function createSortParam(string $attribute): string

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.

Parameters

Parameter	Type	Description
$attribute	string	The attribute name

Returns

string: The value of the sort variable

Throws

• yii\base\InvalidConfigException: if the specified attribute is not defined in $attributes

createUrl()

public function createUrl(string $attribute, bool $absolute = false): string

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.

The target route is determined by resolveRoute() when $route is not configured.

Parameters

Parameter	Type	Description
$attribute	string	The attribute name
$absolute	bool	Whether to create an absolute URL. Defaults to false.

Returns

string: The URL for sorting. False if the attribute is invalid.

Throws

• yii\base\InvalidConfigException: if the attribute is unknown, or if resolveRoute() cannot determine a route.

See also

• $attributeOrders
• $params

getAttributeOrder()

public function getAttributeOrder(string $attribute): int|null

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

Parameters

Parameter	Type	Description
$attribute	string	The attribute name

Returns

int|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 function getAttributeOrders(bool $recalculate = false): array

Returns the currently requested sort information.

Parameters

Parameter	Type	Description
$recalculate	bool	Whether to recalculate the sort directions

Returns

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 function getOrders(bool $recalculate = false): array

Returns the columns and their corresponding sort directions.

Parameters

Parameter	Type	Description
$recalculate	bool	Whether to recalculate the sort directions

Returns

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

hasAttribute()

public function hasAttribute(string $name): bool

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

Parameters

Parameter	Type	Description
$name	string	The attribute name

Returns

bool: Whether the sort definition supports sorting by the named attribute.

init()

public function init(): mixed

Normalizes the $attributes property.

Returns

mixed

link()

public function link(string $attribute, array $options = []): string

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”.

Parameters

Parameter	Type	Description
$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, it will be retrieved from the instance of $modelClass (if $modelClass is not null) or generated from attribute name using Inflector::camel2words(). Note that it will not be HTML-encoded.

Returns

string: The generated hyperlink

Throws

• yii\base\InvalidConfigException: if the attribute is unknown

setAttributeOrders()

public function setAttributeOrders(array|null $attributeOrders, bool $validate = true): mixed

Sets up the currently sort information.

Parameters

Parameter	Type	Description
$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	bool	Whether to validate given attribute orders against $attributes and $enableMultiSort. If validation is enabled incorrect entries will be removed.

Returns

mixed

Since

2.0.10

parseSortParam()

protected function parseSortParam(mixed $param): array

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'
]

Parameters

Parameter	Type	Description
$param	mixed	The value of the $sortParam.

Returns

array: The valid sort attributes.

Since

2.0.12

See also

• $separator (for the attribute name separator.)
• $sortParam

resolveRoute()

protected function resolveRoute(): string

Resolves the target route from $route, the active controller, or Application::$requestedRoute.

The requestedRoute fallback supports standalone actions where no controller is hosting the request.

Returns

string: The resolved route.

Throws

• yii\base\InvalidConfigException: if no route can be resolved.