第八章 扩展Yii

在本章中，我们将会讨论如下话题：

• 创建帮助类
• 创建模型行为
• 创建组件
• 创建可复用控制器动作
• 创建可复用控制器
• 创建一个小组件
• 创建CLI命令
• 创建过滤器
• 创建模块
• 创建一个自定义视图渲染器
• 创建一个多语言应用
• 制作可发布的扩展

介绍

在本章中，我们将会想你展示如何实现自己的Yii扩展，以及如何使自己的扩展可复用，并对社区有用。此外，我们将会关注许多你需要做的事情，使你的扩展尽可能高效。

创建帮助类

有许多内置的框架帮助类，例如yii\helpers命名空间下的StringHelper。这里包含了很多有用的静态方法，用于操纵字符串、文件、数组和其它目标。

在需要情况下，对于额外的行为，你可以创建一个自己的帮助类，并将任何静态函数放在里边。例如，我们在本小节中事先了数字帮助类。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

1. 在你的项目中创建helpers文件夹，以及NumberHelper类：

<?php
namespace app\helpers;
class NumberHelper
{
    public static function format($value, $decimal = 2)
    {
        return number_format($value, $decimal, '.', ',');
    }
}

1. 添加actionNumbers方法到NumberHelper：

<?php
...
class SiteController extends Controller
{
    …
    public function actionNumbers()
    {
        return $this->render('numbers', ['value' => 18878334526.3]);
    }
}

1. 添加views/site/numbers.php视图：

<?php
use app\helpers\NumberHelper;
use yii\helpers\Html;
/* @var $this yii\web\View */
/* @var $value float */
$this->title = 'Numbers';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="site-numbers">
    <h1><?= Html::encode($this->title) ?></h1>
    <p>
        Raw number:<br />
        <b><?= $value ?></b>
    </p>
    <p>
        Formatted number:<br />
        <b><?= NumberHelper::format($value) ?></b>
    </p>
</div>

1. 打开这个动作。你将会看到如下截图：

在其它例子中，你可以指定其它数量的十进制数。观察如下例子：

NumberHelper::format($value, 3)

工作原理…

Yii2中任何帮助类只是函数的集合，在对应的类中以静态方法实现。

你可以使用一个帮助类用于实现任何类型的输出，操纵任何变量的任何值，以及其它例子。

注意：通常，静态帮助类是轻量干净的函数，有少数几个参数。避免将你的业务逻辑和其它复杂的操纵到帮助类中。在其它情况中，使用小组件或者其它组件，而不是帮助类。

参考

欲了解更多信息，参考：

http://www.yiiframework.com/doc-2.0/guide-helper-overview.html

例如对于内置帮助类，参考框架中helpers文件夹下的源代码。对于框架，参考：

https://github.com/yiisoft/yii2/tree/master/framework/helpers。

创建模型行为

现在的web应用中，有许多相似的解决方案。龙头产品例如google的Gmail，有这两个的UI模式。其中一个就是软删除。不需要点击成吨的确认进行永久删除，Gmail允许我们将信息立刻标记为删除，然后可以很容易的撤销它。相同的行为可以应用于任何对象上，例如博客帖子、评论等等。

下边我们来创建一个行为，它将允许我们将模型标记为删除，选择还未删除的模型，删除模型，以及所有的模型。在本小节中，我们将会进行一个测试驱动的开发方法，来计划这个行为，并测试实现是否正确。

准备

1. 按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。
2. 创建两个数据库分别用于工作和测试。
3. 在你的主应用config/db.php中配置Yii来使用第一个数据库。确认测试应用使用第二个数据库tests/codeception/config/config.php。
4. 创建一个新的migration：

<?php
use yii\db\Migration;
class m160427_103115_create_post_table extends Migration
{
    public function up()
    {
        $this->createTable('{{%post}}', [
            'id' => $this->primaryKey(),
            'title' => $this->string()->notNull(),
            'content_markdown' => $this->text(),
            'content_html' => $this->text(),
        ]);
    }
    public function down()
    {
        $this->dropTable('{{%post}}');
    }
}

1. 应用migration到工作和测试数据库上：

./yii migrate
tests/codeception/bin/yii migrate

1. 创建Post模型：

<?php
namespace app\models;
use app\behaviors\MarkdownBehavior;
use yii\db\ActiveRecord;
/**
 * @property integer $id
 * @property string $title
 * @property string $content_markdown
 * @property string $content_html
 */
class Post extends ActiveRecord
{
    public static function tableName()
    {
        return '{{%post}}';
    }
    public function rules()
    {
        return [
            [['title'], 'required'],
            [['content_markdown'], 'string'],
            [['title'], 'string', 'max' => 255],
        ];
    }
}

如何做…

准备一个测试环境，为Post模型定义fixtures。创建文件tests/codeception/unit/fixtures/PostFixture.php：

<?php
namespace app\tests\codeception\unit\fixtures;
use yii\test\ActiveFixture;
class PostFixture extends ActiveFixture
{
    public $modelClass = 'app\models\Post';
    public $dataFile = '@tests/codeception/unit/fixtures/data/post.php';
}

1. 添加一个fixture数据到tests/codeception/unit/fixtures/data/post.php：

<?php
return [
    [
        'id' => 1,
        'title' => 'Post 1',
        'content_markdown' => 'Stored *markdown* text 1',
        'content_html' => "<p>Stored <em>markdown</em> text 1</p>\n",
    ],
];

1. 然后，我们需要创建一个测试用例，tests/codeception/unit/MarkdownBehaviorTest.php：

<?php
namespace app\tests\codeception\unit;
use app\models\Post;
use app\tests\codeception\unit\fixtures\PostFixture;
use yii\codeception\DbTestCase;
class MarkdownBehaviorTest extends DbTestCase
{
    public function testNewModelSave()
    {
        $post = new Post();
        $post->title = 'Title';
        $post->content_markdown = 'New *markdown* text';
        $this->assertTrue($post->save());
        $this->assertEquals("<p>New <em>markdown</em> text</p>\n", $post->content_html);
    }
    public function testExistingModelSave()
    {
        $post = Post::findOne(1);
        $post->content_markdown = 'Other *markdown* text';
        $this->assertTrue($post->save());
        $this->assertEquals("<p>Other <em>markdown</em> text</p>\n", $post->content_html);
    }
    public function fixtures()
    {
        return [
            'posts' => [
                'class' => PostFixture::className(),
            ]
        ];
    }
}

1. 运行单元测试：

codecept run unit MarkdownBehaviorTest
Ensure that tests has not passed:
Codeception PHP Testing Framework v2.0.9
Powered by PHPUnit 4.8.27 by Sebastian Bergmann and
contributors.
Unit Tests (2)
----------------------------------------------------------------
-----------
Trying to test ...
MarkdownBehaviorTest::testNewModelSave Error
Trying to test ...
MarkdownBehaviorTest::testExistingModelSave Error
----------------------------------------------------------------
-----------
Time: 289 ms, Memory: 16.75MB

1. 现在我们需要实现行为，将它附加到模型上，并确保测试通过。创建一个新的文件夹behaviors。在这个文件夹中，创建一个MarkdownBehavior类：

<?php
namespace app\behaviors;
use yii\base\Behavior;
use yii\base\Event;
use yii\base\InvalidConfigException;
use yii\db\ActiveRecord;
use yii\helpers\Markdown;
class MarkdownBehavior extends Behavior
{
    public $sourceAttribute;
    public $targetAttribute;
    public function init()
    {
        if (empty($this->sourceAttribute) ||
            empty($this->targetAttribute)) {
            throw new InvalidConfigException('Source and target must be set.');
        }
        parent::init();
    }
    public function events()
    {
        return [
            ActiveRecord::EVENT_BEFORE_INSERT => 'onBeforeSave',
            ActiveRecord::EVENT_BEFORE_UPDATE => 'onBeforeSave',
        ];
    }
    public function onBeforeSave(Event $event)
    {
        if
        ($this->owner->isAttributeChanged($this->sourceAttribute)) {
            $this->processContent();
        }
    }
    private function processContent()
    {
        $model = $this->owner;
        $source = $model->{$this->sourceAttribute};
        $model->{$this->targetAttribute} =
            Markdown::process($source);
    }
}

1. 附加行为到Post模型上：

class Post extends ActiveRecord
{
    ...
    public function behaviors()
    {
        return [
            'markdown' => [
                'class' => MarkdownBehavior::className(),
                'sourceAttribute' => 'content_markdown',
                'targetAttribute' => 'content_html',
            ],
        ];
    }
}

1. 运行测试并确保通过：

Codeception PHP Testing Framework v2.0.9
Powered by PHPUnit 4.8.27 by Sebastian Bergmann and
contributors.
Unit Tests (2)
----------------------------------------------------------------
-----------
Trying to test ...
MarkdownBehaviorTest::testNewModelSave Ok
Trying to test ...
MarkdownBehaviorTest::testExistingModelSave Ok
----------------------------------------------------------------
-----------
Time: 329 ms, Memory: 17.00MB

1. 完成了。我们已经创建了一个可复用的行为，并可以使用它用于所有未来的项目中，只需要将它连接到一个模型上。

工作原理…

首先看下测试用例。因为我们希望使用模型集，我们定义了fixtures。每次测试方法被执行的时候，一个fixture集合被放到了数据库中。

我们准备单元测试用以说明行为是如何工作的：

• 首先，我们测试一个新的模型内容的处理。这个行为会将source属性中的markdown格式的文本，转换为HTML，并存储在target属性中。
• 第二，我们对更新已有模型的内容进行测试。在修改了markdown内容以后，保存这个模型，我们可以得到更新后的HTML内容。

现在，我们转到有趣的实现细节上。在行为中，我们可以添加我们自己的方法，它将会被混合到附带有行为的模型中。此外，我们可以订阅拥有者的组件事件。我们使用它添加一个自己的监听：

public function events()
{
    return [
        ActiveRecord::EVENT_BEFORE_INSERT => 'onBeforeSave',
        ActiveRecord::EVENT_BEFORE_UPDATE => 'onBeforeSave',
    ];
}

现在，我们可以实现这个监听器：

public function onBeforeSave(Event $event)
{
    if ($this->owner->isAttributeChanged($this->sourceAttribute))
    {
        $this->processContent();
    }
}

在所有的方法中，我们可以使用owner属性来获取附带有行为的对象。一般情况下，我们可以附加任何行为到我们的模型、控制器、应用，以及其它继承了yii\base\Component类的组件。此外，我们可以重复附加一个行为到模型上，用以处理不同的属性：

class Post extends ActiveRecord
{
    ...
    public function behaviors()
    {
        return [
            [
                'class' => MarkdownBehavior::className(),
                'sourceAttribute' => 'description_markdown',
                'targetAttribute' => 'description_html',
            ],
            [
                'class' => MarkdownBehavior::className(),
                'sourceAttribute' => 'content_markdown',
                'targetAttribute' => 'content_html',
            ],
        ];
    }
}

此外，我们可以像yii\behaviors\TimestampBehavior继承yii\base\AttributeBehavior，用以为任何事件更新指定的属性。

参考

为了了解更多关于行为和事件，参考如下页面：

• http://www.yiiframework.com/doc-2.0/guide-concept-behaviors.html
• http://www.yiiframework.com/doc-2.0/guide-concept-events.html

欲了解更多关于markdown语法的信息，参考http://daringfireball.net/projects/markdown/。

此外，参考本章中的制作可发布的扩展小节。

创建组件

如果你有一些代码，看上去可以被复用，但是你不知道它是一个行为、小组件还是其它东西，很有可能它是一个组件。一个组件应该是继承了yii\base\Component类。然后，这个组件可以被附加到应用上，并使用配置文件中的components部分进行配置。这就是同只是使用纯PHP类相比最主要的优点。此外，我们可以得到行为、事件、getter、setter的支持。

在我们的例子中，我们将会实现一个简单的交换应用组件，它能从http://fixer.io获取最新的汇率，将它附加在应用上，并使用它。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

为了得到汇率，我们的组件应该发送一个HTTP GET请求到一个服务地址上，例如http://api.fixer.io/2016-05-14?base=USD。

这个服务会返回所有支持的汇率在最近一天的情况：

{
    "base":"USD",
    "date":"2016-05-13",
    "rates": {
        "AUD":1.3728,
        "BGN":1.7235,
        ...
        "ZAR":15.168,
        "EUR":0.88121
    }
}

这个组件应该从JSON格式的响应解析出汇率，并返回一个目标汇率：

1. 在你的应用结构中创建components文件夹。
2. 使用如下interface创建组件类例子：

<?php
namespace app\components;
use yii\base\Component;
class Exchange extends Component
{
    public function getRate($source, $destination, $date = null)
    {
    }
}

1. 实现这个组件的功能：

<?php
namespace app\components;
use yii\base\Component;
use yii\base\InvalidConfigException;
use yii\base\InvalidParamException;
use yii\caching\Cache;
use yii\di\Instance;
use yii\helpers\Json;
class Exchange extends Component
{
    /**
     * @var string remote host
     */
    public $host = 'http://api.fixer.io';
    /**
     * @var bool cache results or not
     */
    public $enableCaching = false;
    /**
     * @var string|Cache component ID
     */
    public $cache = 'cache';
    public function init()
    {
        if (empty($this->host)) {
            throw new InvalidConfigException('Host must be set.');
        }
        if ($this->enableCaching) {
            $this->cache = Instance::ensure($this->cache,
                Cache::className());
        }
        parent::init();
    }
    public function getRate($source, $destination, $date = null)
    {
        $this->validateCurrency($source);
        $this->validateCurrency($destination);
        $date = $this->validateDate($date);
        $cacheKey = $this->generateCacheKey($source,
            $destination, $date);
        if (!$this->enableCaching || ($result =
                $this->cache->get($cacheKey)) === false) {
            $result = $this->getRemoteRate($source,
                $destination, $date);
            if ($this->enableCaching) {
                $this->cache->set($cacheKey, $result);
            }
        }
        return $result;
    }
    private function getRemoteRate($source, $destination, $date)
    {
        $url = $this->host . '/' . $date . '?base=' . $source;
        $response = Json::decode(file_get_contents($url));
        if (!isset($response['rates'][$destination])) {
            throw new \RuntimeException('Rate not found.');
        }
        return $response['rates'][$destination];
    }
    private function validateCurrency($source)
    {
        if (!preg_match('#^[A-Z]{3}$#s', $source)) {
            throw new InvalidParamException('Invalid currency format.');
        }
    }
    private function validateDate($date)
    {
        if (!empty($date) &&
            !preg_match('#\d{4}\-\d{2}-\d{2}#s', $date)) {
            throw new InvalidParamException('Invalid date format.');
        }
        if (empty($date)) {
            $date = date('Y-m-d');
        }
        return $date;
    }
    private function generateCacheKey($source, $destination,
                                      $date)
    {
        return [__CLASS__, $source, $destination, $date];
    }
}

1. 附加这个组件到你的config/console.php或者config/web.php配置文件中：

'components' => [
    'cache' => [
        'class' => 'yii\caching\FileCache',
    ],
    'exchange' => [
        'class' => 'app\components\Exchange',
        'enableCaching' => true,
    ],
    // ...
    db' => $db,
],

1. 现在，我们可以直接使用一个新的组件，或者使用get方法：

echo \Yii::$app->exchange->getRate('USD', 'EUR');
echo \Yii::$app->get('exchange')->getRate('USD', 'EUR', '2014-04-12');

1. 创建一个实例控制台控制器：

<?php
namespace app\commands;
use yii\console\Controller;
class ExchangeController extends Controller
{
    public function actionTest($currency, $date = null)
    {
        echo \Yii::$app->exchange->getRate('USD', $currency,
                $date) . PHP_EOL;
    }
}

1. 现在尝试运行任何命令：

$ ./yii exchange/test EUR
> 0.90196
$ ./yii exchange/test EUR 2015-11-24
> 0.93888
$ ./yii exchange/test OTHER
> Exception 'yii\base\InvalidParamException' with message 'Invalid currency format.'
$ ./yii exchange/test EUR 2015/24/11
Exception 'yii\base\InvalidParamException' with message 'Invalid date format.'
$ ./yii exchange/test ASD
> Exception 'RuntimeException' with message 'Rate not found.'

作为结果，成功的话，你可以看到汇率值；如果失败你会看到指定的异常错误。此外创建你自己的组件，你可以做的更多。

覆盖已经存在的应用组件

大部分情况下，没有必须创建你自己的应用组件，因为其它类型的扩展，例如小组件或者行为，涵盖了几乎所有类型的可复用代码。但是，复写核心框架组件是一个常用的实践，并且可以被用于自定义框架的行为，用于特殊的需求，而不需要修改核心代码。

例如，为了能够使用Yii::app()->formatter->asNumber($value)格式化数字，而不是在创建帮助类小节中的NumberHelper::format方法，你可以使用如下步骤：

1. 继承yii\i18n\Formatter组件：

<?php
namespace app\components;
class Formatter extends \yii\i18n\Formatter
{
    public function asNumber($value, $decimal = 2)
    {
        return number_format($value, $decimal, '.', ',');
    }
}

1. 复写内置formatter组件的类：

'components' => [
    // ...
    formatter => [
        'class' => 'app\components\Formatter,
    ],
    // ...
],

1. 现在，我们可以直接使用这个方法：

echo Yii::app()->formatter->asNumber(1534635.2, 3);

或者，它可以被用做一个新的格式，用在GridView和DetailView小组件中：

<?= \yii\grid\GridView::widget([
    'dataProvider' => $dataProvider,
    'columns' => [
        'id',
        'created_at:datetime',
        'title',
        'value:number',
    ],
]) ?>

1. 此外，你可以扩展任何已有的组件，而不需要修改源代码。

工作原理…

为了能附加一个组件到一个应用中，它可以从yii\base\Component进行继承。附加非常简单，只需要添加一个新的数组到配置的组件部分。这里class的值指定了组件的类，其它值用于设置这个组件的公共属性和setter方法。

继承它自己非常直接：我们包裹了http://api.fixer.io调用到一个非常舒适的API中，并可以进行校验和缓存。我们可以通过Yii::$app和组件的名称访问我们的类。在我们的例子中，它会是Yii::$app->exchange。

参考

欲了解关于组件的官方信息，参考http://www.yiiframework.com/doc-2.0/guideconcept-components.html。

对于NumberHelper类的源代码，参考创建帮助类小节。

创建可重用控制器动作

常用的动作，例如通过主键删除AR模型，或者从AJAX autocomplete获取数据，可以移到可复用控制器动作中，然后附加到需要的控制器上。

在这个小节中，我们将会创建一个可复用删除动作，它会通过主键删除指定的AR模型。

准备

1. 按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。
2. 创建一个新的数据库并配置它。
3. 创建并应用如下migration：

<?php
use yii\db\Migration;
class m160308_093233_create_post_table extends Migration
{
    public function up()
    {
        $this->createTable('{{%post}}', [
            'id' => $this->primaryKey(),
            'title' => $this->string()->notNull(),
            'text' => $this->text()->notNull(),
        ]);
    }
    public function down()
    {
        $this->dropTable('{{%post}}');
    }
}

1. 使用Gii为帖子和评论生成模型。
2. 在Gii中生成标准的CRUD控制器app\controllers\PostController。
3. 确保CRUD正常工作：

1. 在一个成功的例子中，添加一些帖子示例。

如何做…

执行如下步骤：

1. 创建动作文件夹，添加DeleteAction独立动作：

<?php
namespace app\actions;
use yii\base\Action;
use yii\base\InvalidConfigException;
use yii\web\MethodNotAllowedHttpException;
use yii\web\NotFoundHttpException;
class DeleteAction extends Action
{
    public $modelClass;
    public $redirectTo = ['index'];
    public function init()
    {
        if (empty($this->modelClass)) {
            throw new InvalidConfigException('Empty model class.');
        }
        parent::init();
    }
    public function run($id)
    {
        if (!\Yii::$app->getRequest()->getIsPost()) {
            throw new MethodNotAllowedHttpException('Method not allowed.');
        }
        $model = $this->findModel($id);
        $model->delete();
        return $this->controller->redirect($this->redirectTo);
    }
    /**
     * @param $id
     * @return \yii\db\ActiveRecord
     * @throws NotFoundHttpException
     */
    private function findModel($id)
    {
        $class = $this->modelClass;
        if (($model = $class::findOne($id)) !== null) {
            return $model;
        } else {
            throw new NotFoundHttpException('Page does not exist.');
        }
    }
}

1. 现在我们需要将它附加到controllers/PostController.php控制器中。移除控制器的actionDelete和behaviors方法，并在actions方法中附加你自己的动作：

<?php
namespace app\controllers;
use app\actions\DeleteAction;
use Yii;
use app\models\Post;
use app\models\PostSearch;
use yii\web\Controller;
use yii\web\NotFoundHttpException;
class PostController extends Controller
{
    public function actions()
    {
        return [
            'delete' => [
                'class' => DeleteAction::className(),
                'modelClass' => Post::className(),
            ],
        ];
    }
    public function actionIndex() { ... }
    public function actionView($id) { ... }
    public function actionCreate() { ... }
    public function actionUpdate($id) { ... }
    protected function findModel($id)
    {
        if (($model = Post::findOne($id)) !== null) {
            return $model;
        } else {
            throw new NotFoundHttpException('The requested page does not exist.');
        }
    }
}

1. 完成了。确保删除操作可以正常工作，并且在删除之后，你将会被重定向到一个对应的index动作中。

工作原理…

为了创建一个额外的控制器动作，你需要从yii\base\Action中继承你的类。唯一需要强制实现的方法是run。在我们的例子中，它使用Yii的自动参数绑定特性，从$_GET接收名叫$id的参数，并尝试删除一个对应的模型。

为了是它可配置，我们创建了两个可配置的公共属性。modelName保存了模型的名称，以及redirectTo指定了用户会被重定向的路由。

这个配置本身是通过在你的控制器中实现动作方法来完成的。这里，你可以附加这个动作一次或者多次，并配置它的公共属性。

如果你需要重定向到别的动作，或者渲染一个指定的视图，你可以通过控制器属性，访问原始的控制器对象。

参考

• 欲了解更多关于控制器和动作的信息，参考http://www.yiiframework.com/doc-2.0/guide-structure-controllers.html
• 本章中的创建可复用控制器小节

创建可重用控制器

在Yii中，你可以创建可复用的控制器。如果你创建许多应用或者控制器，他们有相同的类型，将所有常用的代码移动到一个可复用的控制器中将会节省很多时间。

在本小节中，我们将会尝试创建一个常用的CleanController，它会清理临时文件夹以及flush缓存数据。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

执行如下步骤，创建可复用的控制器：

1. 创建cleaner目录，并添加独立CleanController控制器：

<?php
namespace app\cleaner;
use Yii;
use yii\filters\VerbFilter;
use yii\helpers\FileHelper;
use yii\web\Controller;
class CleanController extends Controller
{
    public $assetPaths = ['@app/web/assets'];
    public $runtimePaths = ['@runtime'];
    public $caches = ['cache'];
    public function behaviors()
    {
        return [
            'verbs' => [
                'class' => VerbFilter::className(),
                'actions' => [
                    'assets' => ['post'],
                    'runtime' => ['post'],
                    'cache' => ['post'],
                ],
            ],
        ];
    }
    public function actionIndex()
    {
        return $this->render('@app/cleaner/views/index');
    }
    public function actionAssets()
    {
        foreach ((array)$this->assetPaths as $path) {
            $this->cleanDir($path);
            Yii::$app->session->addFlash(
                'cleaner',
                'Assets path "' . $path . '" is cleaned.'
            );
        }
        return $this->redirect(['index']);
    }
    public function actionRuntime()
    {
        foreach ((array)$this->runtimePaths as $path) {
            $this->cleanDir($path);
            Yii::$app->session->addFlash(
                'cleaner',
                'Runtime path "' . $path . '" is cleaned.'
            );
        }
        return $this->redirect(['index']);
    }
    public function actionCache()
    {
        foreach ((array)$this->caches as $cache) {
            Yii::$app->get($cache)->flush();
            Yii::$app->session->addFlash(
                'cleaner',
                'Cache "' . $cache . '" is cleaned.'
            );
        }
        return $this->redirect(['index']);
    }
    private function cleanDir($dir)
    {
        $iterator = new \DirectoryIterator(Yii::getAlias($dir));
        foreach($iterator as $sub) {
            if(!$sub->isDot() && $sub->isDir()) {
                FileHelper::removeDirectory($sub->getPathname());
            }
        }
    }
}

1. 为actionIndex方法创建cleaner/views/index.php视图文件：actionIndex

<?php
use yii\helpers\Html;
/* @var $this yii\web\View */
$this->title = 'Cleaner';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="clean-index">
    <h1><?= Html::encode($this->title) ?></h1>
    <?php if (Yii::$app->session->hasFlash('cleaner')): ?>
        <?php foreach
        ((array)Yii::$app->session->getFlash('cleaner', []) as
         $message): ?>
            <div class="alert alert-success">
                <?= $message ?>
            </div>
        <?php endforeach; ?>
    <?php endif; ?>
    <p>
        <?= Html::a('Clear Caches', ['cache'], [
            'class' => 'btn btn-primary',
            'data' => [
                'confirm' => 'Are you sure you want to clear all cache data?',
                'method' => 'post',
            ],
        ]) ?>
        <?= Html::a('Clear Assets', ['assets'],
            ['class' => 'btn btn-primary',
                'data' => [
                    'confirm' => 'Are you sure you want to clear all temporary assets?',
                    'method' => 'post',
                ],
            ]) ?>
        <?= Html::a('Clear Runtime', ['runtime'],
            ['class' => 'btn btn-primary',
                'data' => [
                    'confirm' => 'Are you sure you want to clear all runtime files?',
                    'method' => 'post',
                ],
            ]) ?>
    </p>
</div>

1. 配置config/web.php的controllerMap部分，附加控制器到应用中：

$config = [
    'id' => 'basic',
    'basePath' => dirname(__DIR__),
    'bootstrap' => ['log'],
    'controllerMap' => [
        'clean' => 'app\cleaner\CleanController',
    ],
    'components' => [
        ...
    ]
    ...
];

1. 添加一个新的条目到主菜单中：

echo Nav::widget([
    'options' => ['class' => 'navbar-nav navbar-right'],
    'items' => [
        ['label' => 'Home', 'url' => ['/site/index']],
        ['label' => 'Cleaner', 'url' => ['/clean/index']],
        ['label' => 'About', 'url' => ['/site/about']],
        ...
    ],
]);

1. 打开控制器，并清理assets：

1. 如果你用的是yii2高级应用模板，只需要在配置中指定正确的路径：

'controllerMap' => [
    'clean' => 'app\cleaner\CleanController',
    'assetPaths' => [
        '@backend/web/assets',
        '@frontend/web/assets',
    ],
    'runtimePaths' => [
        '@backend/runtime',
        '@frontend/runtime',
        '@console/runtime',
    ],
],

现在我们可以附加这个控制器到任何应用中。

工作原理…

当你运行一个应用时，假如路由是clean/index，指向CleanController::actionIndex，Yii检查controllerMap是否定义了。因为这里我们有一个干净的控制器，Yii会执行它，而不是像常用的方式。

在这个控制器中，我们定义了assetPaths，runtimePaths和caches属性，这能够连接这个控制器到应用的不同路径和缓存结构。当附加这个控制器的时候设置它。

参考

• 为了更多关于控制器和控制器map的信息，参考http://www.yiiframework.com/doc-2.0/guide-structure-controllers.html
• 本章中的创建可复用控制器小节

创建小部件

小部件是视图中可复用的部分，它不仅会渲染一些数据，而且还能依赖于一些逻辑。它甚至可以从模型中获取数据，并使用它自己的视图，所以它就像一个简化的可复用的模块。

下面我们来创建一个小部件，它会使用Google API画一个饼状图。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

1. 创建widgets目录，并添加ChartWidget类：

<?php
namespace app\widgets;
use yii\base\Widget;
class ChartWidget extends Widget
{
    public $title;
    public $width = 300;
    public $height = 200;
    public $data = [];
    public $labels = [];
    public function run()
    {
        $path = 'http://chart.apis.google.com/chart';
        $query = http_build_query([
            'chtt' => $this->title,
            'cht' => 'pc',
            'chs' => $this->width . 'x' . $this->height,
            'chd' => 't:' . implode(',', $this->data),
            'chds' => 'a',
            'chl' => implode('|', $this->labels),
            'chxt' => 'y',
            'chxl' => '0:|0|' . max($this->data)
        ]);
        $url = $path . '?' . $query;
        return $this->render('chart', [
            'url' => $url,
        ]);
    }
}

1. 创建widgets/views/chart.php视图：

<?php
use yii\helpers\Html;
/* @var $this yii\web\View */
/* @var $url string */
?>
<div class="chart">
    <?= Html::img($url) ?>
</div>

1. 创建一个ChartController控制器：

<?php
namespace app\controllers;
use yii\base\Controller;
class ChartController extends Controller
{
    public function actionIndex()
    {
        return $this->render('index');
    }
}

1. 添加views/chart/index.php视图：

<?php
use app\widgets\ChartWidget;
use yii\helpers\Html;
/* @var $this yii\web\View */
$this->title = 'Chart';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="site-about">
    <h1><?= Html::encode($this->title) ?></h1>
    <?= ChartWidget::widget([
        'title' => 'My Chart Diagram',
        'data' => [
            100 - 32,
            32,
        ],
        'labels' => [
            'Big',
            'Small',
        ],
    ]) ?>
</div>

1. 现在尝试运行这个动作。你应该能看到一个饼状图，如下所示：

1. 你可以展示不同尺寸和数据集的图。

工作原理…

和其它类型的扩展一样，我们创建一些可以配置的公共属性，在调用一个小部件时使用它的widget方法。在这个例子中，我们配置了标题、数据集和数据标签。

小部件的主方法是run()。在我们的小部件中，我们生成一个URL，并渲染小部件视图，它使用Google charting API来打印<img>标签。

参考

• 欲了解更多关于小部件的信息，参考http://www.yiiframework.com/doc-2.0/guide-structurewidgets.html
• 本章中的制作可发布的扩展小节

创建CLI命令

Yii有一个好的命令行支持，允许创建可复用的控制台命令。控制台命令比创建web GUI更快。如果你需要为你的应用创建一些工具，可以被开发者或者管理使用，那么控制台命令就是很好的工具。

为了展示如何创建一个控制台命令，我们将会创建一个简单的命令，它会清理一些东西，例如assets和临时文件夹。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

执行如下过程来创建CLI命令：

1. 使用如下代码创建commands/CleanController.php：

<?php
namespace app\commands;
use yii\console\Controller;
use yii\helpers\FileHelper;
/**
 * Removes content of assets and runtime directories.
 */
class CleanController extends Controller
{
    public $assetPaths = ['@app/web/assets'];
    public $runtimePaths = ['@runtime'];
    /**
     * Removes temporary assets.
     */
    public function actionAssets()
    {
        foreach ((array)$this->assetPaths as $path) {
            $this->cleanDir($path);
        }
        $this->stdout('Done' . PHP_EOL);
    }
    /**
     * Removes runtime content.
     */
    public function actionRuntime()
    {
        foreach ((array)$this->runtimePaths as $path) {
            $this->cleanDir($path);
        }
        $this->stdout('Done' . PHP_EOL);
    }
    private function cleanDir($dir)
    {
        $iterator = new
        \DirectoryIterator(\Yii::getAlias($dir));
        foreach($iterator as $sub) {
            if(!$sub->isDot() && $sub->isDir()) {
                $this->stdout('Removed ' . $sub->getPathname()
                    . PHP_EOL);
                FileHelper::removeDirectory($sub->getPathname());
            }
        }
    }
}

1. 现在我们可以使用我们自己的控制台命令。只需要运行yii shell脚本。

./yii

1. 查找自己的clean命令：

This is Yii version 2.0.7.
The following commands are available:
- asset Allows you to combine...
asset/compress Combines and compresses the asset...
asset/template Creates template of configuration
file...
...
- clean Removes content of assets and
runtime directories.
clean/assets Removes temporary assets.
clean/runtime Removes runtime content.
- fixture Manages fixture data loading and
unloading.
fixture/load (default) Loads the specified fixture data.
fixture/unload Unloads the specified fixtures.
...

1. 运行asset清理：

.yii clean/assets

1. 查看处理报告：

Removed /yii-book.app/web/assets/25f82b8a
Removed /yii-book.app/web/assets/9b3b2888
Removed /yii-book.app/web/assets/f4307424
Done

1. 如果你想在yii2-app-advanced应用中使用这个控制器，只需要指定自定义工作路径：

return [
    'id' => 'app-console',
    'basePath' => dirname(__DIR__),
    'bootstrap' => ['log'],
    'controllerNamespace' => 'console\controllers',
    'controllerMap' => [
        'clean' => [
            'class' => 'console\controllers\CleanController',
            'assetPaths' => [
                '@backend/web/assets',
                '@frontend/web/assets',
            ],
            'runtimePaths' => [
                '@backend/runtime',
                '@frontend/runtime',
                '@console/runtime',
            ],
        ],
    ],
// ...
];

工作原理…

所有的控制台命令应该继承yii\console\Controller类。因为所有的控制器命令在yii\console\Application运行，而不是yii\web\Application，我们没有办法来决定@webroot的值。此外，在yii2-app-advanced模板中，默认情况下，我们有前端、后端和控制子目录。对于这个目的，我们创建可配置的公共数据，叫做assetPaths和runtimePaths。

控制台命令结构本身类似一个典型的控制器。我们定义几个动作，然后可以通过yii <console command>/<command action>来执行。

正如你所看到的，没有使用视图，所以我们可以把精力集中在编程任务上，而不需要设计、标记等等。此外，你需要提供一些有用的输出，这样用户就知道现在是什么情况。这可以通过简单的PHP echo语句来完成。

如果你的命令相对复杂，例如使用Yii构建的消息或者migrate，提供额外的描述是一个好的决定，说明可用的选项和动作。它可以通过复写getHelp方法完成：

public function getHelp()
{
    $out = "Clean command allows you to clean up various temporary data Yii and an application are generating.\n\n";
    return $out . parent::getHelp();
}

运行如下命令：

./yii help clean

你会看到如下全部输出：

DESCRIPTION
Clean command allows you to clean up various temporary data Yii and
an application are generating.
Removes content of assets and runtime directories.
SUB-COMMANDS
- clean/assets Removes temporary assets.
- clean/runtime Removes runtime content.

默认情况下，当我们运行shell命令时：

./yii

我们在输出列表中看到了所有命令的简化描述：

- clean Removes content of assets and runtime directories.
    clean/assets Removes temporary assets.
    clean/runtime Removes runtime content.

这个描述将会从类和动作前边的注释中获取：

/**
* Removes content of assets and runtime directories.
*/
class CleanController extends Controller
{
    /**
    * Removes temporary assets.
    */
    public function actionAssets() { … }
    * Removes runtime content.
    */
    public function actionRuntime() { … }
}

为你的类添加描述是可选的。你不用非得为你的CLI命令做这件事。

参考

• 本章中的创建可复用控制器小节
• 本章中制作可发布扩展小节

创建过滤器

过滤器是一个类，它可以在动作之前或者之后执行。它可以被用于修改执行上下文，或者装饰输出。在我们的例子中，我们将会实现一个简单的访问过滤器，它允许用户只能在接受了用户协议之后才能看到私有的内容。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

1. 创建协议表单模型：

<?php
namespace app\models;
use yii\base\Model;
class AgreementForm extends Model
{
    public $accept;
    public function rules()
    {
        return [
            ['accept', 'required'],
            ['accept', 'compare', 'compareValue' => 1,
                'message' => 'You must agree the rules.'],
        ];
    }
    public function attributeLabels()
    {
        return [
            'accept' => 'I completely accept the rules.'
        ];
    }
}

1. 创建协议检查服务：

<?php
namespace app\services;
use Yii;
use yii\web\Cookie;
class AgreementChecker
{
    public function isAllowed()
    {
        return Yii::$app->request->cookies->has('agree');
    }
    public function allowAccess()
    {
        Yii::$app->response->cookies->add(new Cookie([
            'name' => 'agree',
            'value' => 'on',
            'expire' => time() + 3600 * 24 * 90, // 90 days
        ]));
    }
}

它使用了协议cookies进行了封装。

1. 创建filter类：

<?php
namespace app\filters;
use app\services\AgreementChecker;
use Yii;
use yii\base\ActionFilter;
class AgreementFilter extends ActionFilter
{
    public function beforeAction($action)
    {
        $checker = new AgreementChecker();
        if (!$checker->isAllowed()) {
            Yii::$app->response->redirect(['/content/agreement'])->send();
            return false;
        }
        return true;
    }
}

1. 创建内容控制器，并将过滤器附加到行为上：

<?php
namespace app\controllers;
use app\filters\AgreementFilter;
use app\models\AgreementForm;
use app\services\AgreementChecker;
use Yii;
use yii\web\Controller;
class ContentController extends Controller
{
    public function behaviors()
    {
        return [
            [
                'class' => AgreementFilter::className(),
                'only' => ['index'],
            ],
        ];
    }
    public function actionIndex()
    {
        return $this->render('index');
    }
    public function actionAgreement()
    {
        $model = new AgreementForm();
        if ($model->load(Yii::$app->request->post()) &&
            $model->validate()) {
            $checker = new AgreementChecker();
            $checker->allowAccess();
            return $this->redirect(['index']);
        } else {
            return $this->render('agreement', [
                'model' => $model,
            ]);
        }
    }
}

1. 添加私有内容到views/content/index.php：

<?php
use yii\helpers\Html;
/* @var $this yii\web\View */
$this->title = 'Content';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="site-about">
    <h1><?= Html::encode($this->title) ?></h1>
    <div class="well">
        This is our private page.
    </div>
</div>

1. 给表单添加views/content/agreement.php视图：

<?php
use yii\helpers\Html;
use yii\bootstrap\ActiveForm;
/* @var $this yii\web\View */
/* @var $form yii\bootstrap\ActiveForm */
/* @var $model app\models\AgreementForm */
$this->title = 'User agreement';
$this->params['breadcrumbs'][] = $this->title;
?>
<div class="site-login">
    <h1><?= Html::encode($this->title) ?></h1>
    <p>Please agree with our rules:</p>
    <?php $form = ActiveForm::begin(); ?>
    <?= $form->field($model, 'accept')->checkbox() ?>
    <div class="form-group">
        <?= Html::submitButton('Accept', ['class' => 'btn btn-success']) ?>
        <?= Html::a('Cancel', ['/site/index'], ['class' => 'btn btn-danger']) ?>
    </div>
    <?php ActiveForm::end(); ?>
</div>

1. 添加主菜单项到views/layouts/main.php：

echo Nav::widget([
    'options' => ['class' => 'navbar-nav navbar-right'],
    'items' => [
        ['label' => 'Home', 'url' => ['/site/index']],
        ['label' => 'Content', 'url' => ['/content/index']],
        ['label' => 'About', 'url' => ['/site/about']],
    //...
    ],
]);

1. 尝试打开内容页。过滤器会将你重定向到协议页上：

1. 只有在接受协议之后，你才可以看到私有内容：

1. 此外，你可以附加这个过滤器到其他控制器或者模块上。

工作原理…

过滤器应该继承了yii\base\ActionFilter类，它继承了yii\base\Behavior。如果我们想做前过滤或者后过滤，我们可以复写beforeAction或者afterAction方法。

例如，我们可以检查用户访问，并在遇到失败情况时，抛出HTTP异常。在这个小节中，如果指定的cookie的值不存在，我们将用户重定向到协议页上。

class AgreementFilter extends ActionFilter
{
    public function beforeAction($action)
    {
        $checker = new AgreementChecker();
        if (!$checker->isAllowed()) {
            Yii::$app->response->redirect(['/content/agreement'])->send();
            return false;
        }
        return true;
    }
}

你可以附加过滤器到任何控制器或者模块上。为了指定必要路由的列表，只需要使用only或者except选项。例如，我们只为控制器的index动作应用我们的过滤器：

public function behaviors()
{
    return [
        [
            'class' => AgreementFilter::className(),
            'only' => ['index'],
        ],
    ];
}

注意：不要忘记，对于beforeAction方法，成功的时候返回一个true。否则，这个控制器动作将不会被执行。

参考

欲了解更多关于过滤器的信息，参考http://www.yiiframework.com/doc-2.0/guide-structurefilters.html。

对于内置的缓存和访问控制过滤器，参考：

• http://www.yiiframework.com/doc-2.0/guide-caching-http.html
• http://www.yiiframework.com/doc-2.0/guide-securityauthorization.html
• 创建模型行为小节

创建模块

如果你创建了一个复杂的应用部分，并希望他有一些可自定义的自由度，并用于下一个项目中，很可能你需要创建一个模块。在这个小节中，我们将会看到如何创建一个应用日志查看模块。

准备

按照官方指南http://www.yiiframework.com/doc-2.0/guide-start-installation.html的描述，使用Composer包管理器创建一个新的yii2-app-basic应用。

如何做…

首先我们来做一些计划。

在yii2-app-basic中使用缺省配置，所有的日志被存放在runtime/logs/app.log文件中。我们可以使用正则表达式将所有的消息从文件中提取出来，然后将他们展示在GridView小部件上。此外，我们允许用户为日志文件配置自定义路径。

执行如下步骤：

1. 创建modules/log文件夹，并创建Module类文件：

<?php
namespace app\modules\log;
class Module extends \yii\base\Module
{
    public $file = '@runtime/logs/app.log';
}

1. 创建一个简单的模型，用于从日志文件中转换每行内容：

<?php
namespace app\modules\log\models;
use yii\base\Object;
class LogRow extends Object
{
    public $time;
    public $ip;
    public $userId;
    public $sessionId;
    public $level;
    public $category;
    public $text;
}

1. 写一个日志文件读取类，它会解析文件每行内容，逆序排列，返回LogRow模型的实例向量：

<?php
namespace app\modules\log\services;
use app\modules\log\models\LogRow;
class LogReader
{
    public function getRows($file)
    {
        $result = [];
        $handle = @fopen($file, "r");
        if ($handle) {
            while (($row = fgets($handle)) !== false) {
                $pattern =
                    '#^' .
                    '(?P<time>\d{4}\-\d{2}\-\d{2}\d{2}:\d{2}:\d{2}) ' .
                    '\[(?P<ip>[^\]]+)\]' .
                    '\[(?P<userId>[^\]]+)\]' .
                    '\[(?P<sessionId>[^\]]+)\]' .
                    '\[(?P<level>[^\]]+)\]' .
                    '\[(?P<category>[^\]]+)\]' .
                    ' (?P<text>.*?)' .
                    '(\$\_(GET|POST|REQUEST|COOKIE|SERVER) = \[)?' .
                    '$#i';
                if (preg_match($pattern, $row, $matches)) {
                    if ($matches['text']) {
                        $result[] = new LogRow([
                            'time' => $matches['time'],
                            'ip' => $matches['ip'],
                            'userId' => $matches['userId'],
                            'sessionId' =>
                                $matches['sessionId'],
                            'level' => $matches['level'],
                            'category' => $matches['category'],
                            'text' => $matches['text'],
                        ]);
                    }
                }
            }
            fclose($handle);
        }
        return array_reverse($result);
    }
}