namespace yii\base;

 use Yii;
 use ReflectionClass;

 /**
  * Widget is the base class for widgets.
  * Widget是所有小部件的基类
  *
  * @property string $id ID of the widget.
  * @property \yii\web\View $view The view object that can be used to render views or view files. Note that the
  * type of this property differs in getter and setter. See [[getView()]] and [[setView()]] for details.
  * @property string $viewPath The directory containing the view files for this widget. This property is
  * read-only.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
 class Widget extends Component implements ViewContextInterface
 {
     /**
      * @var integer a counter used to generate [[id]] for widgets.
      * @var integer 一个用于生成widget ID的计数器
      * @internal
      */
     public static $counter = 0;
     /**
      * @var string the prefix to the automatically generated widget IDs.
      * @var string widget IDs自动生成的前缀
      * @see getId()
      */
     public static $autoIdPrefix = 'w';
     /**
      * @var Widget[] the widgets that are currently being rendered (not ended). This property
      * is maintained by [[begin()]] and [[end()]] methods.
      * @var 目前正在呈现的小部件
      * @internal
      */
     public static $stack = [];

     /**
      * Begins a widget.
      * 开始一个小部件
      * This method creates an instance of the calling class. It will apply the configuration
      * to the created instance. A matching [[end()]] call should be called later.
      * 该方法将应用配置文件创建调用类的实例，有一个[[end()]]方法相对应
      * @param array $config name-value pairs that will be used to initialize the object properties
      * @return static the newly created widget instance
      */
     public static function begin($config = [])
     {
         $config['class'] = get_called_class();// get_called_class -- 后期静态绑定（"Late Static Binding"）类的名称
                                               // 就是用那个类调用的这个方法，就返回那个类，返回值中带有 namespace
         /* @var $widget Widget */
         $widget = Yii::createObject($config);//通过类名和传入的配置，实例化调用类
         static::$stack[] = $widget;//将实例放入正在呈现的小部件堆栈中

         return $widget;//返回小部件实例
     }

     /**
      * Ends a widget.
      * 结束一个小部件
      * Note that the rendering result of the widget is directly echoed out.
      * @return static the widget instance that is ended.
      * @throws InvalidCallException if [[begin()]] and [[end()]] calls are not properly nested
      */
     public static function end()
     {
         if (!empty(static::$stack)) {//正在呈现的小部件堆栈中存在调用类实例
             $widget = array_pop(static::$stack);//则从堆栈中删除最后一个实例--调用当前小部件的实例
             if (get_class($widget) === get_called_class()) {//如果删除的实例的类名和当前调用类的类名相同
                 echo $widget->run();//输出小部件的内容
                 return $widget;//返回调用类实例
             } else {
                 throw new InvalidCallException('Expecting end() of ' . get_class($widget) . ', found ' . get_called_class());
             }
         } else {//抛出异常，未找到对应的begin()开始方法
             throw new InvalidCallException('Unexpected ' . get_called_class() . '::end() call. A matching begin() is not found.');
         }
     }

     /**
      * Creates a widget instance and runs it.
      * 创建一个widget实例，并运行它
      * The widget rendering result is returned by this method.
      * widget的渲染结果将被该方法返回
      * @param array $config name-value pairs that will be used to initialize the object properties
      * @return string the rendering result of the widget.
      * @throws \Exception
      */
     public static function widget($config = [])
     {
         ob_start();//打开一个输出缓冲区，所有的输出信息不再直接发送到浏览器，而是保存在输出缓冲区里面
         ob_implicit_flush(false);//打开或关闭绝对刷新，默认为关闭，打开后ob_implicit_flush(true)，
           //所谓绝对刷新，即当有输出语句(e.g: echo)被执行时，便把输出直接发送到浏览器，而不再需要调用flush()或等到脚本结束时才输出
         try {
             /* @var $widget Widget */
             $config['class'] = get_called_class();//获取调用类的类名
             $widget = Yii::createObject($config);//实例化调用类
             $out = $widget->run();//运行widget
         } catch (\Exception $e) {
             // close the output buffer opened above if it has not been closed already
             if (ob_get_level() > 0) {//返回输出缓冲机制的嵌套级别
                 ob_end_clean();//删除内部缓冲区的内容，关闭缓冲区(不输出)
             }
             throw $e;
         }

         return ob_get_clean() . $out;//返回内部缓冲区的内容，关闭缓冲区
     }