0 追蹤者

類別 yii\behaviors\SluggableBehavior

所有類別 | 屬性 | 方法
繼承關係yii\behaviors\SluggableBehavior » yii\behaviors\AttributeBehavior » yii\base\Behavior » yii\base\BaseObject
實作介面yii\base\Configurable
自版本2.0
原始碼 https://github.com/yiisoft/yii2/blob/master/framework/behaviors/SluggableBehavior.php

SluggableBehavior 會自動將指定屬性填入可用於 URL slug 的值。

注意：此行為依賴 php-intl 擴充套件進行音譯。如果未安裝，則會退回至 yii\helpers\Inflector::$transliteration 中定義的替換。

若要使用 SluggableBehavior，請將以下程式碼插入您的 ActiveRecord 類別

use yii\behaviors\SluggableBehavior;

public function behaviors()
{
    return [
        [
            'class' => SluggableBehavior::class,
            'attribute' => 'title',
            // 'slugAttribute' => 'slug',
        ],
    ];
}

預設情況下，當關聯的 AR 物件正在驗證時，SluggableBehavior 會將 slug 屬性填入可用於 URL slug 的值。

由於屬性值將由此行為自動設定，因此它們通常不是使用者輸入，因此不應進行驗證，即 slug 屬性不應出現在模型的 rules() 方法中。

如果您的屬性名稱不同，您可以設定 $slugAttribute 屬性，如下所示

public function behaviors()
{
    return [
        [
            'class' => SluggableBehavior::class,
            'slugAttribute' => 'alias',
        ],
    ];
}

公開屬性

隱藏繼承的屬性

屬性 類型 描述 定義於
$attribute string|array|null 將轉換為 slug 的屬性或屬性列表，或 null 表示將使用 $value 屬性來產生 slug。 yii\behaviors\SluggableBehavior
$attributes array 要自動填入透過 $value 指定的值的屬性列表。 yii\behaviors\AttributeBehavior
$ensureUnique boolean 是否確保產生的 slug 值在擁有者類別記錄中是唯一的。 yii\behaviors\SluggableBehavior
$immutable boolean 是否在 slug 已經產生過後產生新的 slug。 yii\behaviors\SluggableBehavior
$owner yii\base\Component|null 此行為的擁有者 yii\base\Behavior
$preserveNonEmptyValues boolean 是否保留非空的屬性值。 yii\behaviors\AttributeBehavior
$skipOnEmpty boolean 如果 $attribute 為 null 或空字串，是否跳過 slug 產生。 yii\behaviors\SluggableBehavior
$skipUpdateOnClean boolean 當 $owner 未被修改時，是否跳過此行為 yii\behaviors\AttributeBehavior
$slugAttribute string 將接收 slug 值的屬性 yii\behaviors\SluggableBehavior
$uniqueSlugGenerator callable|null Slug 唯一值產生器。 yii\behaviors\SluggableBehavior
$uniqueValidator array Slug 唯一性驗證器的設定。 yii\behaviors\SluggableBehavior
$value callable|string|null 將用作 slug 的值。 yii\behaviors\SluggableBehavior

公開方法

隱藏繼承的方法

方法 描述 定義於
__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
attach() 將行為物件附加到元件。 yii\base\Behavior
canGetProperty() 傳回值，指示屬性是否可以讀取。 yii\base\BaseObject
canSetProperty() 傳回值，指示屬性是否可以設定。 yii\base\BaseObject
className() 傳回此類別的完整限定名稱。 yii\base\BaseObject
detach() 從元件分離行為物件。 yii\base\Behavior
evaluateAttributes() 評估屬性值並將其指派給目前的屬性。 yii\behaviors\AttributeBehavior
events() 為 $owner 的事件宣告事件處理器。 yii\behaviors\AttributeBehavior
hasMethod() 傳回值，指示是否已定義方法。 yii\base\BaseObject
hasProperty() 傳回值，指示是否已定義屬性。 yii\base\BaseObject
init() 初始化物件。 yii\behaviors\SluggableBehavior

保護方法

隱藏繼承的方法

方法 描述 定義於
generateSlug() 此方法由 getValue() 呼叫以產生 slug。 yii\behaviors\SluggableBehavior
generateUniqueSlug() 使用設定的回呼或迭代增量產生 slug。 yii\behaviors\SluggableBehavior
getValue() 傳回目前屬性的值。 yii\behaviors\SluggableBehavior
isEmpty() 檢查 $slugPart 是否為空字串或 null。 yii\behaviors\SluggableBehavior
isNewSlugNeeded() 檢查是否需要產生新的 slug。此方法由 getValue() 呼叫，以檢查是否需要產生新的 slug。 yii\behaviors\SluggableBehavior
makeUnique() 當 $ensureUnique 為 true 時，此方法由 getValue() 呼叫，以產生唯一的 slug。 yii\behaviors\SluggableBehavior
validateSlug() 檢查給定的 slug 值是否為唯一。 yii\behaviors\SluggableBehavior

屬性詳細資訊

隱藏繼承的屬性

$attribute 公開屬性

將轉換為 slug 的屬性或屬性列表，或 null 表示將使用 $value 屬性來產生 slug。

public string|array|null $attribute = null
$ensureUnique 公開屬性

是否確保產生的 slug 值在擁有者類別記錄中是唯一的。如果啟用，行為將自動驗證 slug 的唯一性。如果驗證失敗，它將嘗試從基礎值產生唯一的 slug 值，直到成功。

public boolean $ensureUnique = false
$immutable 公開屬性 (自版本 2.0.2 起可用)

如果已產生 slug，是否產生新的 slug。如果為 true，即使 $attribute 已變更，行為也不會產生新的 slug。

public boolean $immutable = false
$skipOnEmpty 公開屬性 (自版本 2.0.13 起可用)

如果 $attribute 為 null 或空字串，是否跳過 slug 產生。如果為 true，則當 $attribute 為 null 或空字串時，行為將不會產生新的 slug。

public boolean $skipOnEmpty = false
$slugAttribute 公開屬性

將接收 slug 值的屬性

public string $slugAttribute = 'slug'
$uniqueSlugGenerator 公開屬性

Slug 唯一值產生器。在啟用 $ensureUnique 且產生的 slug 不是唯一的情況下使用。這應該是一個具有以下簽章的 PHP 可呼叫物件

function ($baseSlug, $iteration, $model)
{
    // return uniqueSlug
}

如果未設定，將會透過在基本 slug 中新增遞增後綴來產生唯一 slug。

public callable|null $uniqueSlugGenerator = null
$uniqueValidator 公開屬性

Slug 唯一性驗證器的組態。可以省略參數 'class' - 預設將使用 yii\validators\UniqueValidator。

另請參閱 yii\validators\UniqueValidator。

public array $uniqueValidator = []
$value 公開屬性

將用作 slug 的值。這可以是匿名函式或任意值或 null。如果是前者，則函式的傳回值將用作 slug。如果為 null，則將使用 $attribute 屬性產生 slug。函式的簽章應如下所示，

function ($event)
{
    // return slug
}
public callable|string|null $value = null

方法詳細資訊

隱藏繼承的方法

__call() 公開方法

定義於： yii\base\BaseObject::__call()

呼叫非類別方法的具名方法。

請勿直接呼叫此方法，因為它是一個 PHP 魔術方法，當調用未知方法時將會隱式呼叫。

public mixed __call ( $name, $params )
$name string

方法名稱
$params array

方法參數
return mixed

方法傳回值
throws 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

屬性名稱
return mixed

屬性值
throws yii\base\UnknownPropertyException

如果未定義屬性
throws 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.dev.org.tw/manual/en/function.isset.php。

public boolean __isset ( $name )
$name string

屬性名稱或事件名稱
return 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 mixed

屬性值
throws yii\base\UnknownPropertyException

如果未定義屬性
throws 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.dev.org.tw/manual/en/function.unset.php。

public void __unset ( $name )
$name string

屬性名稱
throws 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);
    }
}
attach() 公開方法

定義於： yii\base\Behavior::attach()

將行為物件附加到元件。

預設實作將設定 $owner 屬性，並附加在 events() 中宣告的事件處理器。如果您覆寫此方法，請務必呼叫父類別實作。

public void attach ( $owner )
$owner yii\base\Component

此行為要附加到的元件。

 

                public function attach($owner)
{
    $this->owner = $owner;
    foreach ($this->events() as $event => $handler) {
        $this->_attachedEvents[$event] = $handler;
        $owner->on($event, is_string($handler) ? [$this, $handler] : $handler);
    }
}
canGetProperty() 公開方法

定義於： yii\base\BaseObject::canGetProperty()

傳回值，指示屬性是否可以讀取。

如果屬性可讀取

  • 類別具有與指定名稱相關聯的 getter 方法 (在此情況下，屬性名稱不區分大小寫)；
  • 類別具有具有指定名稱的成員變數 (當 $checkVars 為 true 時)；

另請參閱 canSetProperty()。

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

屬性名稱
$checkVars boolean

是否將成員變數視為屬性
return 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

是否將成員變數視為屬性
return 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 ( )
return string

此類別的完整限定名稱。

 

                public static function className()
{
    return get_called_class();
}
detach() 公開方法

定義於： yii\base\Behavior::detach()

從元件分離行為物件。

預設實作將取消設定 $owner 屬性，並分離在 events() 中宣告的事件處理器。如果您覆寫此方法，請務必呼叫父類別實作。

public void detach ( )

                public function detach()
{
    if ($this->owner) {
        foreach ($this->_attachedEvents as $event => $handler) {
            $this->owner->off($event, is_string($handler) ? [$this, $handler] : $handler);
        }
        $this->_attachedEvents = [];
        $this->owner = null;
    }
}
evaluateAttributes() 公開方法

定義於： yii\behaviors\AttributeBehavior::evaluateAttributes()

評估屬性值並將其指派給目前的屬性。

public void evaluateAttributes ( $event )
$event yii\base\Event 

                public function evaluateAttributes($event)
{
    if (
        $this->skipUpdateOnClean
        && $event->name == ActiveRecord::EVENT_BEFORE_UPDATE
        && empty($this->owner->dirtyAttributes)
    ) {
        return;
    }
    if (!empty($this->attributes[$event->name])) {
        $attributes = (array) $this->attributes[$event->name];
        $value = $this->getValue($event);
        foreach ($attributes as $attribute) {
            // ignore attribute names which are not string (e.g. when set by TimestampBehavior::updatedAtAttribute)
            if (is_string($attribute)) {
                if ($this->preserveNonEmptyValues && !empty($this->owner->$attribute)) {
                    continue;
                }
                $this->owner->$attribute = $value;
            }
        }
    }
}
events() 公開方法

定義於： yii\behaviors\AttributeBehavior::events()

為 $owner 的事件宣告事件處理器。

子類別可以覆寫此方法，以宣告應將哪些 PHP 回呼附加到 $owner 元件的事件。

當行為附加到擁有者時，回呼將附加到 $owner 的事件；當行為從元件分離時，回呼將從事件中分離。

回呼可以是以下任何一種

  • 此行為中的方法：'handleClick'，等效於 [$this, 'handleClick']
  • 物件方法：[$object, 'handleClick']
  • 靜態方法：['Page', 'handleClick']
  • 匿名函式：function ($event) { ... }

以下是一個範例

[
    Model::EVENT_BEFORE_VALIDATE => 'myBeforeValidate',
    Model::EVENT_AFTER_VALIDATE => 'myAfterValidate',
]
public array events ( )
return array

事件 (陣列鍵) 和對應的事件處理器方法 (陣列值)。

 

                public function events()
{
    return array_fill_keys(
        array_keys($this->attributes),
        'evaluateAttributes'
    );
}
generateSlug() 保護方法

此方法由 getValue() 呼叫以產生 slug。

您可以覆寫它來自訂 slug 產生。預設實作在以破折號 (-) 連接的輸入字串上呼叫 yii\helpers\Inflector::slug()。

protected string generateSlug ( $slugParts )
$slugParts array

應該串連並轉換以產生 slug 值的字串陣列。
return string

轉換結果。

 

                protected function generateSlug($slugParts)
{
    return Inflector::slug(implode('-', $slugParts));
}
generateUniqueSlug() 保護方法

使用設定的回呼或迭代增量產生 slug。

protected string generateUniqueSlug ( $baseSlug, $iteration )
$baseSlug string

基本 slug 值
$iteration 整數

迭代次數
return string

新的 slug 值
throws yii\base\InvalidConfigException 

                protected function generateUniqueSlug($baseSlug, $iteration)
{
    if (is_callable($this->uniqueSlugGenerator)) {
        return call_user_func($this->uniqueSlugGenerator, $baseSlug, $iteration, $this->owner);
    }
    return $baseSlug . '-' . ($iteration + 1);
}
getValue() 保護方法

傳回目前屬性的值。

此方法由 evaluateAttributes() 呼叫。其傳回值將指派給對應於觸發事件的屬性。

protected mixed getValue ( $event )
$event yii\base\Event

觸發目前屬性更新的事件。
return mixed

屬性值

 

                protected function getValue($event)
{
    if (!$this->isNewSlugNeeded()) {
        return $this->owner->{$this->slugAttribute};
    }
    if ($this->attribute !== null) {
        $slugParts = [];
        foreach ((array) $this->attribute as $attribute) {
            $part = ArrayHelper::getValue($this->owner, $attribute);
            if ($this->skipOnEmpty && $this->isEmpty($part)) {
                return $this->owner->{$this->slugAttribute};
            }
            $slugParts[] = $part;
        }
        $slug = $this->generateSlug($slugParts);
    } else {
        $slug = parent::getValue($event);
    }
    return $this->ensureUnique ? $this->makeUnique($slug) : $slug;
}
hasMethod() 公開方法

定義於： yii\base\BaseObject::hasMethod()

傳回值，指示是否已定義方法。

預設實作是對 php 函式 method_exists() 的呼叫。當您實作 php 魔術方法 __call() 時，您可以覆寫此方法。

public boolean hasMethod ( $name )
$name string

方法名稱
return 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

是否將成員變數視為屬性
return boolean

屬性是否已定義

 

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

初始化物件。

在物件使用給定組態初始化後，於建構子的結尾調用此方法。

public void init ( )

                public function init()
{
    parent::init();
    if (empty($this->attributes)) {
        $this->attributes = [BaseActiveRecord::EVENT_BEFORE_VALIDATE => $this->slugAttribute];
    }
    if ($this->attribute === null && $this->value === null) {
        throw new InvalidConfigException('Either "attribute" or "value" property must be specified.');
    }
}
isEmpty() 保護方法 (自版本 2.0.13 起可用)

檢查 $slugPart 是否為空字串或 null。

protected boolean isEmpty ( $slugPart )
$slugPart string

用於 slug 產生的一個屬性。
return boolean

$slugPart 是否為空。

 

                protected function isEmpty($slugPart)
{
    return $slugPart === null || $slugPart === '';
}
isNewSlugNeeded() 保護方法 (自版本 2.0.7 起可用)

檢查是否需要產生新的 slug。此方法由 getValue() 呼叫，以檢查是否需要產生新的 slug。

您可以覆寫它來自訂檢查。

protected boolean isNewSlugNeeded ( )

                protected function isNewSlugNeeded()
{
    if (empty($this->owner->{$this->slugAttribute})) {
        return true;
    }
    if ($this->immutable) {
        return false;
    }
    if ($this->attribute === null) {
        return true;
    }
    foreach ((array) $this->attribute as $attribute) {
        if ($this->owner->isAttributeChanged($attribute)) {
            return true;
        }
    }
    return false;
}
makeUnique() 保護方法 (自版本 2.0.7 起可用)

當 $ensureUnique 為 true 時，此方法由 getValue() 呼叫，以產生唯一的 slug。

呼叫 generateUniqueSlug() 直到產生的 slug 是唯一的並傳回它。

另請參閱

protected string makeUnique ( $slug )
$slug string

基本 slug 值
return string

唯一的 slug

 

                protected function makeUnique($slug)
{
    $uniqueSlug = $slug;
    $iteration = 0;
    while (!$this->validateSlug($uniqueSlug)) {
        $iteration++;
        $uniqueSlug = $this->generateUniqueSlug($slug, $iteration);
    }
    return $uniqueSlug;
}
validateSlug() 受保護方法

檢查給定的 slug 值是否為唯一。

protected boolean validateSlug ( $slug )
$slug string

Slug 值
return boolean

Slug 是否為唯一。

 

                protected function validateSlug($slug)
{
    /* @var $validator UniqueValidator */
    /* @var $model BaseActiveRecord */
    $validator = Yii::createObject(array_merge(
        [
            'class' => UniqueValidator::className(),
        ],
        $this->uniqueValidator
    ));
    $model = clone $this->owner;
    $model->clearErrors();
    $model->{$this->slugAttribute} = $slug;
    $validator->validateAttribute($model, $this->slugAttribute);
    return !$model->hasErrors();
}