Instance类， 表示依赖注入容器或服务定位器中对某一个对象的引用
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()来获取实际对象
}
}
}