namespace yii\di;

 use Yii;
 use yii\base\InvalidConfigException;

 /**
  * Instance represents a reference to a named object in a dependency injection (DI) container or a service locator.
  * Instance 表示依赖注入容器或服务定位器中对某一个对象的引用
  *
  * You may use [[get()]] to obtain the actual object referenced by [[id]].
  * 可以通过使用[[get()]]方法和[[id]]获取实际对象的引用
  *
  * Instance is mainly used in two places:
  * Instance 主要在两个地方被使用：
  *
  * - When configuring a dependency injection container, you use Instance to reference a class name, interface name
  *   or alias name. The reference can later be resolved into the actual object by the container.
  *   在配置“依赖注入容器”时，可以使用Instance引用一个类名称、接口名称或别名。该引用将被容器将解析为实际的对象
  * - In classes which use service locator to obtain dependent objects.
  *   在类中使用服务定位器获取依赖对象时。
  *
  * The following example shows how to configure a DI container with Instance:
  *
  * ```php
  * $container = new \yii\di\Container;
  * $container->set('cache', 'yii\caching\DbCache', Instance::of('db'));
  * $container->set('db', [
  *     'class' => 'yii\db\Connection',
  *     'dsn' => 'sqlite:path/to/file.db',
  * ]);
  * ```
  *
  * And the following example shows how a class retrieves a component from a service locator:
  *
  * ```php
  * class DbCache extends Cache
  * {
  *     public $db = 'db';
  *
  *     public function init()
  *     {
  *         parent::init();
  *         $this->db = Instance::ensure($this->db, 'yii\db\Connection');
  *     }
  * }
  * ```
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
 class Instance
 {
     /**
      * @var string the component ID, class name, interface name or alias name
      * @var string 用于保存类名、接口名或者别名
      */
     public $id;

     /**
      * Constructor.
      * 构造函数，仅将传入的ID赋值给 $id 属性
      * @param string $id the component ID
      */
     protected function __construct($id)
     {
         $this->id = $id;
     }

     /**
      * Creates a new Instance object.
      * 静态方法创建一个Instance实例
      * @param string $id the component ID
      * @return Instance the new Instance object.
      */
     public static function of($id)
     {
         return new static($id);//实例化访问该方法的类
     }

     /**
      * Resolves the specified reference into the actual object and makes sure it is of the specified type.
      * 静态方法，用于将引用解析成实际的对象，并确保这个对象的类型
      *
      * The reference may be specified as a string or an Instance object. If the former,
      * it will be treated as a component ID, a class/interface name or an alias, depending on the container type.
      *
      * If you do not specify a container, the method will first try `Yii::$app` followed by `Yii::$container`.
      *
      * For example,
      *
      * ```php
      * use yii\db\Connection;
      *
      * // returns Yii::$app->db
      * $db = Instance::ensure('db', Connection::className());
      * // returns an instance of Connection using the given configuration
      * $db = Instance::ensure(['dsn' => 'sqlite:path/to/my.db'], Connection::className());
      * ```
      *
      * @param object|string|array|static $reference an object or a reference to the desired object.
      * You may specify a reference in terms of a component ID or an Instance object.
      * Starting from version 2.0.2, you may also pass in a configuration array for creating the object.
      * If the "class" value is not specified in the configuration array, it will use the value of `$type`.
      * @param string $type the class/interface name to be checked. If null, type check will not be performed.
      * @param ServiceLocator|Container $container the container. This will be passed to [[get()]].
      * @return object the object referenced by the Instance, or `$reference` itself if it is an object.
      * @throws InvalidConfigException if the reference is invalid
      */
     public static function ensure($reference, $type = null, $container = null)
     {
         if (is_array($reference)) {//如果$reference是数组
             $class = isset($reference['class']) ? $reference['class'] : $type;//$reference中有类名，则将类名赋值给$class，否则将$type赋值给$class
             if (!$container instanceof Container) {//如果$container不是Container的实例
                 $container = Yii::$container;//则取Yii中定义的Container对象
             }
             unset($reference['class']);
             return $container->get($class, [], $reference);//返回引用的实例
         } elseif (empty($reference)) {//如果$reference为空，则抛出异常
             throw new InvalidConfigException('The required component is not specified.');
         }

         if (is_string($reference)) {//如果$reference是字符串
             $reference = new static($reference);//则实例化该引用类
         } elseif ($type === null || $reference instanceof $type) {//如果给定检查的类为空或者$reference是给定检查的类的实例
             return $reference;//返回该实例
         }

         if ($reference instanceof self) {//如果$reference是Istance的实例
             $component = $reference->get($container);//则获取调用$container的组件的对象
             if ($type === null || $component instanceof $type) {//如果给定检查的类为空或者$component是给定检查的类的实例
                 return $component;//返回$component
             } else {//否则抛出异常 跟预期的类型不符合
                 throw new InvalidConfigException('"' . $reference->id . '" refers to a ' . get_class($component) . " component. $type is expected.");
             }
         }

         $valueType = is_object($reference) ? get_class($reference) : gettype($reference);
         throw new InvalidConfigException("Invalid data type: $valueType. $type is expected.");
     }

     /**
      * Returns the actual object referenced by this Instance object.
      * 获取这个实例所引用的实际对象，它调用的是yii\di\Container::get()来获取实际对象
      * @param ServiceLocator|Container $container the container used to locate the referenced object.
      * If null, the method will first try `Yii::$app` then `Yii::$container`.
      * @return object the actual object referenced by this Instance object.
      */
     public function get($container = null)
     {
         if ($container) {
             return $container->get($this->id);//如果传入$container容器，则调用$container中的get方法获取引用的实际对象
         }
         if (Yii::$app && Yii::$app->has($this->id)) {//如果该对象已有实例
             return Yii::$app->get($this->id);//返回该实例
         } else {
             return Yii::$container->get($this->id);//否则调用yii\di\Container::get()来获取实际对象
         }
     }
 }