README

为 Yii 框架提供现代化的标签行为。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令

$ composer require creocoder/yii2-taggable

或者在您的 composer.json 文件的 require 部分添加以下内容：

"creocoder/yii2-taggable": "~2.0"

迁移

运行以下命令

$ yii migrate/create create_post_table

打开文件 /path/to/migrations/m_xxxxxx_xxxxxx_create_post_table.php，在 up() 方法中添加以下内容：

$this->createTable('{{%post}}', [
    'id' => Schema::TYPE_PK,
    'title' => Schema::TYPE_STRING . ' NOT NULL',
    'body' => Schema::TYPE_TEXT . ' NOT NULL',
]);

运行以下命令

$ yii migrate/create create_tag_table

打开文件 /path/to/migrations/m_xxxxxx_xxxxxx_create_tag_table.php，在 up() 方法中添加以下内容：

$this->createTable('{{%tag}}', [
    'id' => Schema::TYPE_PK,
    'name' => Schema::TYPE_STRING . ' NOT NULL',
    'frequency' => Schema::TYPE_INTEGER . ' NOT NULL DEFAULT 0',
]);

运行以下命令

$ yii migrate/create create_post_tag_assn_table

打开文件 /path/to/migrations/m_xxxxxx_xxxxxx_create_post_tag_assn_table.php，在 up() 方法中添加以下内容：

$this->createTable('{{%post_tag_assn}}', [
    'post_id' => Schema::TYPE_INTEGER . ' NOT NULL',
    'tag_id' => Schema::TYPE_INTEGER . ' NOT NULL',
]);

$this->addPrimaryKey('', '{{%post_tag_assn}}', ['post_id', 'tag_id']);

配置

按照以下方式配置模型

use creocoder\taggable\TaggableBehavior;

/**
 * ...
 * @property string $tagValues
 */
class Post extends \yii\db\ActiveRecord
{
    public function behaviors()
    {
        return [
            'taggable' => [
                'class' => TaggableBehavior::className(),
                // 'tagValuesAsArray' => false,
                // 'tagRelation' => 'tags',
                // 'tagValueAttribute' => 'name',
                // 'tagFrequencyAttribute' => 'frequency',
            ],
        ];
    }

    public function rules()
    {
        return [
            //...
            ['tagValues', 'safe'],
        ];
    }

    public function transactions()
    {
        return [
            self::SCENARIO_DEFAULT => self::OP_ALL,
        ];
    }

    public static function find()
    {
        return new PostQuery(get_called_class());
    }

    public function getTags()
    {
        return $this->hasMany(Tag::className(), ['id' => 'tag_id'])
            ->viaTable('{{%post_tag_assn}}', ['post_id' => 'id']);
    }
}

模型 Tag 可以使用 Gii 生成。

按照以下方式配置查询类

use creocoder\taggable\TaggableQueryBehavior;

class PostQuery extends \yii\db\ActiveQuery
{
    public function behaviors()
    {
        return [
            TaggableQueryBehavior::className(),
        ];
    }
}

使用

为实体设置标签

要将标签设置到实体中

$post = new Post();

// through string
$post->tagValues = 'foo, bar, baz';

// through array
$post->tagValues = ['foo', 'bar', 'baz'];

向实体添加标签

要将标签添加到实体中

$post = Post::findOne(1);

// through string
$post->addTagValues('bar, baz');

// through array
$post->addTagValues(['bar', 'baz']);

从实体中移除标签

要从实体中移除标签

$post = Post::findOne(1);

// through string
$post->removeTagValues('bar, baz');

// through array
$post->removeTagValues(['bar', 'baz']);

从实体中移除所有标签

要从实体中移除所有标签

$post = Post::findOne(1);
$post->removeAllTagValues();

从实体中获取标签

要从实体中获取标签

$posts = Post::find()->with('tags')->all();

foreach ($posts as $post) {
    // as string
    $tagValues = $post->tagValues;

    // as array
    $tagValues = $post->getTagValues(true);
}

getTagValues 方法的返回类型也可以通过 tagValuesAsArray 属性全局配置。

检查实体中的标签

要检查实体中的标签

$post = Post::findOne(1);

// through string
$result = $post->hasTagValues('foo, bar');

// through array
$result = $post->hasTagValues(['foo', 'bar']);

通过任何标签搜索实体

要通过任何标签搜索实体

// through string
$posts = Post::find()->anyTagValues('foo, bar')->all();

// through array
$posts = Post::find()->anyTagValues(['foo', 'bar'])->all();

使用自定义标签模型属性通过任何标签搜索实体

// through string
$posts = Post::find()->anyTagValues('foo-slug, bar-slug', 'slug')->all();

// through array
$posts = Post::find()->anyTagValues(['foo-slug', 'bar-slug'], 'slug')->all();

通过所有标签搜索实体

要通过所有标签搜索实体

// through string
$posts = Post::find()->allTagValues('foo, bar')->all();

// through array
$posts = Post::find()->allTagValues(['foo', 'bar'])->all();

使用自定义标签模型属性通过所有标签搜索实体

// through string
$posts = Post::find()->allTagValues('foo-slug, bar-slug', 'slug')->all();

// through array
$posts = Post::find()->allTagValues(['foo-slug', 'bar-slug'], 'slug')->all();

通过标签搜索相关实体

要通过标签搜索相关实体

// through string
$posts = Post::find()->relatedByTagValues('foo, bar')->all();

// through array
$posts = Post::find()->relatedByTagValues(['foo', 'bar'])->all();

使用自定义标签模型属性通过标签搜索相关实体

// through string
$posts = Post::find()->relatedByTagValues('foo-slug, bar-slug', 'slug')->all();

// through array
$posts = Post::find()->relatedByTagValues(['foo-slug', 'bar-slug'], 'slug')->all();

捐赠

通过 gratipay 支持此项目和 creocoder 的其他项目。