<?php

namespace yii\base;

use Yii;

/**

 * Action是所有控制器动作类的基类，它继承组件类

 *

 * 动作提供了重用动作方法代码的方法，

 * Action类中的动作方法可以用于多个控制器或不同的项目中。

 *

 * 派生类必须实现一个方法叫` run() `

 * 当请求操作时，该方法将由控制器调用

 * `run()` 方法的参数由用户根据他们的名字自动输入的值确定

 * 例如, `run()`方法以以下形式定义

 *

 * ```php

 * public function run($id, $type = 'book') { ... }

 * ```

 *

 * 为动作提供的参数是: `['id' => 1]`.

 * 然后 `run()` 方法 `run(1)` 自动调用.

 *

 * @property string $uniqueId 此动作在整个应用程序中的唯一标识. 此属性只读

 *

 * @author Qiang Xue <qiang.xue@gmail.com>

 * @since 2.0

 */

class Action extends Component

{

    /**

     * @var 动作id

     */

    public $id;

    /**

     * @var Controller|\yii\web\Controller 拥有此动作的控制器

     */

    public $controller;

    /**

     * 构造方法.

     *

     * @param string $id 当前控制器id

     * @param Controller $controller 拥有此动作的控制器

     * @param array $config 将用于初始化对象属性的名称-值对

     */

    public function __construct($id, $controller, $config = [])

    {

        $this->id = $id;

        $this->controller = $controller;

        parent::__construct($config);

    }

    /**

     * 返回此操作在整个应用程序中的唯一标识

     *

     * @return string the unique ID of this action among the whole application.

     */

    public function getUniqueId()

    {

        return $this->controller->getUniqueId() . '/' . $this->id;

    }

    /**

     * 使用指定的参数运行此操作

     * 此方法主要由控制器调用

     *

     * @param array $params 要绑定到行动的run()方法的参数

     * @return 行动的结果  命名参数是否有效的

     * @throws InvalidConfigException if the action class does not have a run() method

     */

    public function runWithParams($params)

    {

        if (!method_exists($this, 'run')) {

            //如果动作类没有run()方法 抛出异常

            throw new InvalidConfigException(get_class($this) . ' must define a "run()" method.');

        }

         //调用bindActionParams()方法将参数绑定到动作。

        $args = $this->controller->bindActionParams($this, $params);

        //记录跟踪消息

        Yii::trace('Running action: ' . get_class($this) . '::run()', __METHOD__);

        if (Yii::$app->requestedParams === null) {

            //请求的动作提供的参数

            Yii::$app->requestedParams = $args;

        }

        if ($this->beforeRun()) {

             //执行run()方法

            $result = call_user_func_array([$this, 'run'], $args);

            $this->afterRun();

            return $result;

        } else {

            return null;

        }

    }

    /**

     * 这种方法被称为右前` run() `执行

     * 可以重写此方法为动作运行做准备工作

     * 如果该方法返回false，则将取消该操作

     *

     * @return boolean whether to run the action.

     */

    protected function beforeRun()

    {

        return true;

    }

    /**

     * 这种方法被称为后` run() `执行

     * 可以重写此方法为动作运行做后处理工作

     */

    protected function afterRun()

    {

    }

}