0 关注者

类 yii\data\Sort

所有类 | 属性 | 方法
继承关系yii\data\Sort » yii\base\BaseObject
实现接口yii\base\Configurable
可用版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/data/Sort.php

Sort 表示与排序相关的信息。

当需要根据一个或多个属性对数据进行排序时，我们可以使用 Sort 来表示排序信息并生成相应的超链接，这些超链接可以引导到排序操作。

一个典型的用法示例如下：

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,
    ]);
}

视图

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

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

在上面，我们声明了两个支持排序的 $attributes：name 和 age。我们将排序信息传递给 Article 查询，以便查询结果按照 Sort 对象指定的顺序进行排序。在视图中，我们显示了两个超链接，可以引导到按相应属性排序的数据页面。

有关 Sort 的更多详细信息和使用信息，请参阅 排序指南文章。

公共属性

隐藏继承的属性

属性 类型 描述 定义于
$attributeOrders array 以属性名称为索引的排序方向。 yii\data\Sort
$attributes array 允许排序的属性列表。 yii\data\Sort
$defaultOrder array|null 当当前请求未指定任何排序顺序时，应使用的排序顺序。 yii\data\Sort
$enableMultiSort boolean 排序是否可以同时应用于多个属性。 yii\data\Sort
$modelClass string|null 由 link() 方法用于检索属性标签的基于 yii\base\Model 的类的名称。 yii\data\Sort
$orders array 列（键）及其对应的排序方向（值）。 yii\data\Sort
$params array|null 用于获取当前排序方向和创建新的排序 URL 的参数（名称 => 值）。 yii\data\Sort
$route string|null 用于显示排序内容的控制器操作的路由。 yii\data\Sort
$separator string 用于分隔需要按其排序的不同属性的字符。 yii\data\Sort
$sortFlags integer 允许控制将传递给 ArrayHelper::multisort() 的第四个参数的值 yii\data\Sort
$sortParam string 指定要按哪个属性以哪个方向排序的参数的名称。 yii\data\Sort
$urlManager yii\web\UrlManager|null 用于创建排序 URL 的 URL 管理器。 yii\data\Sort

公共方法

隐藏继承的方法

方法 描述 定义于
__call() 调用不是类方法的命名方法。 yii\base\BaseObject
__construct() 构造函数。 yii\base\BaseObject
__get() 返回对象属性的值。 yii\base\BaseObject
__isset() 检查属性是否已设置，即定义且不为 null。 yii\base\BaseObject
__set() 设置对象属性的值。 yii\base\BaseObject
__unset() 将对象属性设置为 null。 yii\base\BaseObject
canGetProperty() 返回一个值，指示属性是否可以读取。 yii\base\BaseObject
canSetProperty() 返回一个值，指示属性是否可以设置。 yii\base\BaseObject
className() 返回此类的完全限定名称。 yii\base\BaseObject
createSortParam() 为指定的属性创建排序变量。 yii\data\Sort
createUrl() 创建用于按指定属性排序数据的 URL。 yii\data\Sort
getAttributeOrder() 返回当前请求中指定属性的排序方向。 yii\data\Sort
getAttributeOrders() 返回当前请求的排序信息。 yii\data\Sort
getOrders() 返回列及其对应的排序方向。 yii\data\Sort
hasAttribute() 返回一个值，指示排序定义是否支持按命名属性排序。 yii\data\Sort
hasMethod() 返回一个值，指示方法是否已定义。 yii\base\BaseObject
hasProperty() 返回一个值，指示属性是否已定义。 yii\base\BaseObject
init() 规范化 $attributes 属性。 yii\data\Sort
link() 生成一个超链接，该链接链接到排序操作以按指定属性排序。 yii\data\Sort
setAttributeOrders() 设置当前排序信息。 yii\data\Sort

受保护的方法

隐藏继承的方法

方法 描述 定义于
parseSortParam() 将 $sortParam 的值解析为一个排序属性数组。 yii\data\Sort

属性详情

隐藏继承的属性

$attributeOrders 公共属性

以属性名称为索引的排序方向。排序方向可以是 SORT_ASC（升序）或 SORT_DESC（降序）。请注意，此属性在 getter 和 setter 中的类型不同。有关详细信息，请参阅 getAttributeOrders() 和 setAttributeOrders()。

public array $attributeOrders = null
$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',
    ],
]

在上面，声明了两个属性：age 和 name。age 属性是一个简单属性，等效于以下内容

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

从 2.0.12 开始，还可以将特定的排序方向指定为直接排序表达式，如下所示

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

name 属性是一个复合属性

  • name 键表示属性名称，它将出现在指向排序操作的 URL 中。
  • asc 和 desc 元素分别指定如何按升序和降序对属性进行排序。它们的值分别表示应按其排序的实际列和方向。
  • default 元素指定如果当前未排序属性应按哪个方向排序（默认值为升序）。
  • 当调用 link() 创建排序链接时，label 元素指定要使用的标签。如果未设置，则会调用 yii\helpers\Inflector::camel2words() 获取标签。请注意，它不会进行 HTML 编码。

请注意，如果 Sort 对象已经创建，则只能使用完整格式配置每个属性。每个属性必须包含以下元素：asc 和 desc。

public 数组 $attributes = []
$defaultOrder 公共属性

当当前请求未指定任何排序顺序时，应使用的排序顺序。数组键是属性名称，数组值是相应的排序方向。例如，

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

另请参阅 $attributeOrders。

public 数组|空 $defaultOrder = null
$enableMultiSort 公共属性

是否可以同时对多个属性应用排序。默认为 false，这意味着每次数据只能按一个属性排序。

public 布尔值 $enableMultiSort = false
$modelClass 公共属性 (自版本 2.0.49 起可用)

yii\base\Model 基类名称，由 link() 方法用于检索属性的标签。有关详细信息，请参阅 link() 方法。

public 字符串|空 $modelClass = null
$orders 公共属性

列（键）及其相应的排序方向（值）。这可以传递给 yii\db\Query::orderBy() 以构建数据库查询。

public 数组 $orders = null
$params 公共属性

用于获取当前排序方向和创建新的排序 URL 的参数（名称 => 值）。如果未设置，则将使用 $_GET 代替。

为了向所有链接添加哈希值，请使用 array_merge($_GET, ['#' => 'my-hash'])。

索引为 $sortParam 的数组元素被认为是当前排序方向。如果该元素不存在，则将使用 默认排序顺序。

另请参阅

public 数组|空 $params = null
$route 公共属性

用于显示已排序内容的控制器操作的路由。如果未设置，则表示使用当前请求的路由。

public 字符串|空 $route = null
$separator 公共属性

用于分隔需要按其排序的不同属性的字符。

public 字符串 $separator = ','
$sortFlags 公共属性 (自版本 2.0.33 起可用)

允许控制将传递给 ArrayHelper::multisort() 的第四个参数的值

public 整数 $sortFlags = SORT_REGULAR
$sortParam 公共属性

指定按哪个属性以哪个方向排序的参数的名称。默认为 sort。

另请参阅 $params。

public 字符串 $sortParam = 'sort'
$urlManager 公共属性

用于创建排序 URL 的 URL 管理器。如果未设置，则将使用 urlManager 应用程序组件。

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

方法详情

隐藏继承的方法

__call() 公共方法

定义于： yii\base\BaseObject::__call()

调用不是类方法的命名方法。

不要直接调用此方法，因为它是一个 PHP 魔术方法，当调用未知方法时会隐式调用。

public 混合 __call ( $name, $params )
$name string

方法名
$params array

方法参数
返回值 混合

方法返回值
抛出 yii\base\UnknownMethodException

调用未知方法时

 

                public function __call($name, $params)
{
    throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}
__construct() 公共方法

定义于： yii\base\BaseObject::__construct()

构造函数。

默认实现执行两件事

  • 使用给定的配置 $config 初始化对象。
  • 调用 init()。

如果在子类中重写此方法，建议

  • 构造函数的最后一个参数为配置数组，例如此处为 $config。
  • 在构造函数的末尾调用父类的实现。
public void __construct ( $config = [] )
$config array

用于初始化对象属性的键值对

 

                public function __construct($config = [])
{
    if (!empty($config)) {
        Yii::configure($this, $config);
    }
    $this->init();
}
__get() 公共方法

定义于： yii\base\BaseObject::__get()

返回对象属性的值。

不要直接调用此方法，因为它是一个 PHP 魔术方法，在执行 $value = $object->property; 时会隐式调用。

另请参阅 __set()。

public mixed __get ( $name )
$name string

属性名称
返回值 混合

属性值
抛出 yii\base\UnknownPropertyException

如果未定义属性
抛出 yii\base\InvalidCallException

如果属性为只写

 

                public function __get($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter();
    } elseif (method_exists($this, 'set' . $name)) {
        throw new InvalidCallException('Getting write-only property: ' . get_class($this) . '::' . $name);
    }
    throw new UnknownPropertyException('Getting unknown property: ' . get_class($this) . '::' . $name);
}
__isset() 公共方法

定义于： yii\base\BaseObject::__isset()

检查属性是否已设置，即定义且不为 null。

不要直接调用此方法，因为它是一个 PHP 魔术方法，在执行 isset($object->property) 时会隐式调用。

请注意，如果未定义属性，则将返回 false。

另请参阅 https://php.ac.cn/manual/en/function.isset.php。

public boolean __isset ( $name )
$name string

属性名称或事件名称
返回值 boolean

命名的属性是否已设置（非 null）。

 

                public function __isset($name)
{
    $getter = 'get' . $name;
    if (method_exists($this, $getter)) {
        return $this->$getter() !== null;
    }
    return false;
}
__set() 公共方法

定义于： yii\base\BaseObject::__set()

设置对象属性的值。

不要直接调用此方法，因为它是一个 PHP 魔术方法，在执行 $object->property = $value; 时会隐式调用。

另请参阅 __get()。

public void __set ( $name, $value )
$name string

属性名称或事件名称
$value 混合

属性值
抛出 yii\base\UnknownPropertyException

如果未定义属性
抛出 yii\base\InvalidCallException

如果属性为只读

 

                public function __set($name, $value)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        $this->$setter($value);
    } elseif (method_exists($this, 'get' . $name)) {
        throw new InvalidCallException('Setting read-only property: ' . get_class($this) . '::' . $name);
    } else {
        throw new UnknownPropertyException('Setting unknown property: ' . get_class($this) . '::' . $name);
    }
}
__unset() 公共方法

定义于： yii\base\BaseObject::__unset()

将对象属性设置为 null。

不要直接调用此方法，因为它是一个 PHP 魔术方法，在执行 unset($object->property) 时会隐式调用。

请注意，如果未定义属性，则此方法将不执行任何操作。如果属性为只读，则会引发异常。

另请参阅 https://php.ac.cn/manual/en/function.unset.php。

public void __unset ( $name )
$name string

属性名称
抛出 yii\base\InvalidCallException

如果属性为只读。

 

                public function __unset($name)
{
    $setter = 'set' . $name;
    if (method_exists($this, $setter)) {
        $this->$setter(null);
    } elseif (method_exists($this, 'get' . $name)) {
        throw new InvalidCallException('Unsetting read-only property: ' . get_class($this) . '::' . $name);
    }
}
canGetProperty() 公共方法

定义于： yii\base\BaseObject::canGetProperty()

返回一个值，指示属性是否可以读取。

如果属性可读，则

  • 类具有与指定名称关联的 getter 方法（在这种情况下，属性名称不区分大小写）；
  • 类具有与指定名称相同的成员变量（当 $checkVars 为 true 时）；

另请参阅 canSetProperty()。

public boolean canGetProperty ( $name, $checkVars = true )
$name string

属性名称
$checkVars boolean

是否将成员变量视为属性
返回值 boolean

属性是否可读

 

                public function canGetProperty($name, $checkVars = true)
{
    return method_exists($this, 'get' . $name) || $checkVars && property_exists($this, $name);
}
canSetProperty() 公共方法

定义于： yii\base\BaseObject::canSetProperty()

返回一个值，指示属性是否可以设置。

如果属性可写，则

  • 类具有与指定名称关联的 setter 方法（在这种情况下，属性名称不区分大小写）；
  • 类具有与指定名称相同的成员变量（当 $checkVars 为 true 时）；

另请参阅 canGetProperty()。

public boolean canSetProperty ( $name, $checkVars = true )
$name string

属性名称
$checkVars boolean

是否将成员变量视为属性
返回值 boolean

属性是否可写

 

                public function canSetProperty($name, $checkVars = true)
{
    return method_exists($this, 'set' . $name) || $checkVars && property_exists($this, $name);
}
className() 公共静态方法
自 2.0.14 版本起已弃用。在 PHP >=5.5 上，请改用 ::class。

定义于： yii\base\BaseObject::className()

返回此类的完全限定名称。

public static string className ( )
返回值 string

此类的完全限定名称。

 

                public static function className()
{
    return get_called_class();
}
createSortParam() 公共方法

为指定的属性创建排序变量。

新创建的排序变量可用于创建 URL，该 URL 将导致按指定属性排序。

public string createSortParam ( $attribute )
$attribute string

属性名称
返回值 string

排序变量的值
抛出 yii\base\InvalidConfigException

如果在 $attributes 中未定义指定的属性

 

                public function createSortParam($attribute)
{
    if (!isset($this->attributes[$attribute])) {
        throw new InvalidConfigException("Unknown attribute: $attribute");
    }
    $definition = $this->attributes[$attribute];
    $directions = $this->getAttributeOrders();
    if (isset($directions[$attribute])) {
        if ($this->enableMultiSort) {
            if ($directions[$attribute] === SORT_ASC) {
                $direction = SORT_DESC;
            } else {
                $direction = null;
            }
        } else {
            $direction = $directions[$attribute] === SORT_DESC ? SORT_ASC : SORT_DESC;
        }
        unset($directions[$attribute]);
    } else {
        $direction = isset($definition['default']) ? $definition['default'] : SORT_ASC;
    }
    if ($this->enableMultiSort) {
        if ($direction !== null) {
            $directions = array_merge([$attribute => $direction], $directions);
        }
    } else {
        $directions = [$attribute => $direction];
    }
    $sorts = [];
    foreach ($directions as $attribute => $direction) {
        $sorts[] = $direction === SORT_DESC ? '-' . $attribute : $attribute;
    }
    return implode($this->separator, $sorts);
}
createUrl() 公共方法

创建用于按指定属性排序数据的 URL。

此方法将考虑由 $attributeOrders 给出的当前排序状态。例如，如果当前页面已按指定属性升序对数据进行排序，则创建的 URL 将指向按指定属性降序对数据进行排序的页面。

另请参阅

public string createUrl ( $attribute, $absolute = false )
$attribute string

属性名称
$absolute boolean

是否创建绝对 URL。默认为 false。
返回值 string

排序的 URL。如果属性无效，则为 false。
抛出 yii\base\InvalidConfigException

如果属性未知

 

                public function createUrl($attribute, $absolute = false)
{
    if (($params = $this->params) === null) {
        $request = Yii::$app->getRequest();
        $params = $request instanceof Request ? $request->getQueryParams() : [];
    }
    $params[$this->sortParam] = $this->createSortParam($attribute);
    $params[0] = $this->route === null ? Yii::$app->controller->getRoute() : $this->route;
    $urlManager = $this->urlManager === null ? Yii::$app->getUrlManager() : $this->urlManager;
    if ($absolute) {
        return $urlManager->createAbsoluteUrl($params);
    }
    return $urlManager->createUrl($params);
}
getAttributeOrder() 公共方法

返回当前请求中指定属性的排序方向。

public integer|null getAttributeOrder ( $attribute )
$attribute string

属性名称
返回值 integer|null

属性的排序方向。可以是 SORT_ASC 表示升序或 SORT_DESC 表示降序。如果属性无效或不需要排序，则返回 Null。

 

                public function getAttributeOrder($attribute)
{
    $orders = $this->getAttributeOrders();
    return isset($orders[$attribute]) ? $orders[$attribute] : null;
}
getAttributeOrders() 公共方法

返回当前请求的排序信息。

public array getAttributeOrders ( $recalculate = false )
$recalculate boolean

是否重新计算排序方向
返回值 array

以属性名称为索引的排序方向。排序方向可以是 SORT_ASC 表示升序，或 SORT_DESC 表示降序。

 

                public function getAttributeOrders($recalculate = false)
{
    if ($this->_attributeOrders === null || $recalculate) {
        $this->_attributeOrders = [];
        if (($params = $this->params) === null) {
            $request = Yii::$app->getRequest();
            $params = $request instanceof Request ? $request->getQueryParams() : [];
        }
        if (isset($params[$this->sortParam])) {
            foreach ($this->parseSortParam($params[$this->sortParam]) as $attribute) {
                $descending = false;
                if (strncmp($attribute, '-', 1) === 0) {
                    $descending = true;
                    $attribute = substr($attribute, 1);
                }
                if (isset($this->attributes[$attribute])) {
                    $this->_attributeOrders[$attribute] = $descending ? SORT_DESC : SORT_ASC;
                    if (!$this->enableMultiSort) {
                        return $this->_attributeOrders;
                    }
                }
            }
            return $this->_attributeOrders;
        }
        if (empty($this->_attributeOrders) && is_array($this->defaultOrder)) {
            $this->_attributeOrders = $this->defaultOrder;
        }
    }
    return $this->_attributeOrders;
}
getOrders() 公共方法

返回列及其对应的排序方向。

public array getOrders ( $recalculate = false )
$recalculate boolean

是否重新计算排序方向
返回值 array

列（键）及其相应的排序方向（值）。这可以传递给 yii\db\Query::orderBy() 以构建数据库查询。

 

                public function getOrders($recalculate = false)
{
    $attributeOrders = $this->getAttributeOrders($recalculate);
    $orders = [];
    foreach ($attributeOrders as $attribute => $direction) {
        $definition = $this->attributes[$attribute];
        $columns = $definition[$direction === SORT_ASC ? 'asc' : 'desc'];
        if (is_array($columns) || $columns instanceof \Traversable) {
            foreach ($columns as $name => $dir) {
                $orders[$name] = $dir;
            }
        } else {
            $orders[] = $columns;
        }
    }
    return $orders;
}
hasAttribute() 公共方法

返回一个值，指示排序定义是否支持按命名属性排序。

public boolean hasAttribute ( $name )
$name string

属性名称
返回值 boolean

排序定义是否支持按指定属性名称排序。

 

                public function hasAttribute($name)
{
    return isset($this->attributes[$name]);
}
hasMethod() 公共方法

定义于： yii\base\BaseObject::hasMethod()

返回一个值，指示方法是否已定义。

默认实现是调用 PHP 函数 method_exists()。当您实现了 PHP 魔术方法 __call() 时，您可以覆盖此方法。

public boolean hasMethod ( $name )
$name string

方法名
返回值 boolean

方法是否已定义

 

                public function hasMethod($name)
{
    return method_exists($this, $name);
}
hasProperty() 公共方法

定义于： yii\base\BaseObject::hasProperty()

返回一个值，指示属性是否已定义。

如果满足以下条件，则表示属性已定义

  • 类具有与指定名称关联的 getter 或 setter 方法（在这种情况下，属性名称不区分大小写）；
  • 类具有与指定名称相同的成员变量（当 $checkVars 为 true 时）；

另请参阅

public boolean hasProperty ( $name, $checkVars = true )
$name string

属性名称
$checkVars boolean

是否将成员变量视为属性
返回值 boolean

属性是否已定义

 

                public function hasProperty($name, $checkVars = true)
{
    return $this->canGetProperty($name, $checkVars) || $this->canSetProperty($name, false);
}
init() 公共方法

规范化 $attributes 属性。

public void init ( )

                public function init()
{
    $attributes = [];
    foreach ($this->attributes as $name => $attribute) {
        if (!is_array($attribute)) {
            $attributes[$attribute] = [
                'asc' => [$attribute => SORT_ASC],
                'desc' => [$attribute => SORT_DESC],
            ];
        } elseif (!isset($attribute['asc'], $attribute['desc'])) {
            $attributes[$name] = array_merge([
                'asc' => [$name => SORT_ASC],
                'desc' => [$name => SORT_DESC],
            ], $attribute);
        } else {
            $attributes[$name] = $attribute;
        }
    }
    $this->attributes = $attributes;
}
link() 公共方法

生成一个超链接，该链接链接到排序操作以按指定属性排序。

根据排序方向，生成的超链接的 CSS 类将附加 “asc” 或 “desc”。

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

要按其排序数据的属性名称。
$options array

超链接标签的其他 HTML 属性。有一个特殊的属性 label 将用作超链接的标签。如果未设置，则将使用 $attributes 中定义的标签。如果未定义标签，则将从 $modelClass 的实例中检索（如果 $modelClass 不为空），或使用 yii\helpers\Inflector::camel2words() 从属性名称生成。请注意，它不会进行 HTML 编码。
返回值 string

生成的超链接
抛出 yii\base\InvalidConfigException

如果属性未知

parseSortParam() 受保护的方法 (自版本 2.0.12 起可用)

将 $sortParam 的值解析为一个排序属性数组。

格式必须仅为属性名称（用于升序）或以 - 为前缀的属性名称（用于降序）。

例如，以下返回值将导致按 category 升序排序，并按 created_at 降序排序

[
    'category',
    '-created_at'
]

另请参阅

protected array parseSortParam ( $param )
$param string

$sortParam 的值。
返回值 array

有效的排序属性。

 

                protected function parseSortParam($param)
{
    return is_scalar($param) ? explode($this->separator, $param) : [];
}
setAttributeOrders() 公共方法 (自版本 2.0.10 起可用)

设置当前排序信息。

public void setAttributeOrders ( $attributeOrders, $validate = true )
$attributeOrders array|null

以属性名称为索引的排序方向。排序方向可以是 SORT_ASC 表示升序，或 SORT_DESC 表示降序。
$validate boolean

是否根据 $attributes 和 $enableMultiSort 验证给定的属性顺序。如果启用了验证，则会删除不正确的条目。

 

                public function setAttributeOrders($attributeOrders, $validate = true)
{
    if ($attributeOrders === null || !$validate) {
        $this->_attributeOrders = $attributeOrders;
    } else {
        $this->_attributeOrders = [];
        foreach ($attributeOrders as $attribute => $order) {
            if (isset($this->attributes[$attribute])) {
                $this->_attributeOrders[$attribute] = $order;
                if (!$this->enableMultiSort) {
                    break;
                }
            }
        }
    }
}