namespace yii\di;

 use Yii;
 use Closure;
 use yii\base\Component;
 use yii\base\InvalidConfigException;

 /**
  * ServiceLocator implements a [service locator](http://en.wikipedia.org/wiki/Service_locator_pattern).
  *
  * To use ServiceLocator, you first need to register component IDs with the corresponding component
  * definitions with the locator by calling [[set()]] or [[setComponents()]].
  * You can then call [[get()]] to retrieve a component with the specified ID. The locator will automatically
  * instantiate and configure the component according to the definition.
  *
  * For example,
  *
  * ```php
  * $locator = new \yii\di\ServiceLocator;
  * $locator->setComponents([
  *     'db' => [
  *         'class' => 'yii\db\Connection',
  *         'dsn' => 'sqlite:path/to/file.db',
  *     ],
  *     'cache' => [
  *         'class' => 'yii\caching\DbCache',
  *         'db' => 'db',
  *     ],
  * ]);
  *
  * $db = $locator->get('db');  // or $locator->db
  * $cache = $locator->get('cache');  // or $locator->cache
  * ```
  *
  * Because [[\yii\base\Module]] extends from ServiceLocator, modules and the application are all service locators.
  *
  * @property array $components The list of the component definitions or the loaded component instances (ID =>
  * definition or instance).
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
 class ServiceLocator extends Component
 {
     /**
      * @var array shared component instances indexed by their IDs
      * @var array 用于缓存服务、组件等的实例,索引为ID
      */
     private $_components = [];
     /**
      * @var array component definitions indexed by their IDs
      * @var array 用于保存服务和组件的定义，通常为配置数组，可以用来创建具体的实例
      */
     private $_definitions = [];

     /**
      * Getter magic method.
      * 重写了 getter 方法，使得访问服务和组件就跟访问类的属性一样。同时，也保留了原来Component的 getter所具有的功能。
      * This method is overridden to support accessing components like reading properties.
      * @param string $name component or property name
      * @return mixed the named property value
      */
     public function __get($name)
     {
         if ($this->has($name)) {//调用has方法判断是否有某个组件或服务的实例，如果有调用get方法返回该实例
             return $this->get($name);
         } else {//否则把$name当普通属性处理
             return parent::__get($name);
         }
     }

     /**
      * Checks if a property value is null.
      * 重写了 isset 方法，增加了对是否具有某个服务和组件的判断
      * This method overrides the parent implementation by checking if the named component is loaded.
      * @param string $name the property name or the event name
      * @return boolean whether the property value is null
      */
     public function __isset($name)
     {
         if ($this->has($name, true)) {//调用has方法判断是否有某个组件或服务的实例，如果有返回true
             return true;
         } else {//否则判断是否有$name这个属性
             return parent::__isset($name);
         }
     }

     /**
      * Returns a value indicating whether the locator has the specified component definition or has instantiated the component.
      * This method may return different results depending on the value of `$checkInstance`.
      * 当 $checkInstance === false 时，用于判断是否已经定义了某个服务或组件
      * 当 $checkInstance === true 时，用于判断是否已经有了某个服务或组件的实例
      *
      * - If `$checkInstance` is false (default), the method will return a value indicating whether the locator has the specified
      *   component definition.
      * - If `$checkInstance` is true, the method will return a value indicating whether the locator has
      *   instantiated the specified component.
      *
      * @param string $id component ID (e.g. `db`).
      * @param boolean $checkInstance whether the method should check if the component is shared and instantiated.
      * @return boolean whether the locator has the specified component definition or has instantiated the component.
      * @see set()
      */
     public function has($id, $checkInstance = false)
     {
         return $checkInstance ? isset($this->_components[$id]) : isset($this->_definitions[$id]);
     }

     /**
      * Returns the component instance with the specified ID.
      * 根据 $id 获取对应的服务或组件的实例
      *
      * @param string $id component ID (e.g. `db`).
      * @param boolean $throwException whether to throw an exception if `$id` is not registered with the locator before.
      * @return object|null the component of the specified ID. If `$throwException` is false and `$id`
      * is not registered before, null will be returned.
      * @throws InvalidConfigException if `$id` refers to a nonexistent component ID
      * @see has()
      * @see set()
      */
     public function get($id, $throwException = true)
     {
         if (isset($this->_components[$id])) {//如果_components中有该组件或者服务的实例
             return $this->_components[$id];//返回该实例
         }

         if (isset($this->_definitions[$id])) {//如果_definitions中定义了该组件或者服务
             $definition = $this->_definitions[$id];//取得该组件或者服务的值
             if (is_object($definition) && !$definition instanceof Closure) {//如果该值是对象实例且不是Closure（匿名）的实例
                 return $this->_components[$id] = $definition;//则在_components注册该组件或者服务的实例并返回
             } else {
                 return $this->_components[$id] = Yii::createObject($definition);//否则根据定义中的配置参数创建实例并注册返回
             }
         } elseif ($throwException) {//如果允许抛出异常，则抛出异常
             throw new InvalidConfigException("Unknown component ID: $id");
         } else {//否则返回null
             return null;
         }
     }

     /**
      * Registers a component definition with this locator.
      * 用于注册一个组件或服务，其中 $id 用于标识服务或组件。
      * $definition 可以是一个类名，一个配置数组，一个PHP callable（回调函数），或者一个对象
      *
      * For example,
      *
      * ```php
      * // a class name
      * $locator->set('cache', 'yii\caching\FileCache');
      *
      * // a configuration array
      * $locator->set('db', [
      *     'class' => 'yii\db\Connection',
      *     'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
      *     'username' => 'root',
      *     'password' => '',
      *     'charset' => 'utf8',
      * ]);
      *
      * // an anonymous function
      * $locator->set('cache', function ($params) {
      *     return new \yii\caching\FileCache;
      * });
      *
      * // an instance
      * $locator->set('cache', new \yii\caching\FileCache);
      * ```
      *
      * If a component definition with the same ID already exists, it will be overwritten.
      *
      * @param string $id component ID (e.g. `db`).
      * @param mixed $definition the component definition to be registered with this locator.
      * It can be one of the following:
      *
      * - a class name
      * - a configuration array: the array contains name-value pairs that will be used to
      *   initialize the property values of the newly created object when [[get()]] is called.
      *   The `class` element is required and stands for the the class of the object to be created.
      * - a PHP callable: either an anonymous function or an array representing a class method (e.g. `['Foo', 'bar']`).
      *   The callable will be called by [[get()]] to return an object associated with the specified component ID.
      * - an object: When [[get()]] is called, this object will be returned.
      *
      * @throws InvalidConfigException if the definition is an invalid configuration array
      */
     public function set($id, $definition)
     {
         if ($definition === null) {//如果$definition为null，即只传入$id，表示删除
             unset($this->_components[$id], $this->_definitions[$id]);
             return;
         }

         unset($this->_components[$id]);//开始时清空_components中的id

         if (is_object($definition) || is_callable($definition, true)) {//如果传入的$definition是一个类名一个PHP callable（回调函数），或者一个对象
             // an object, a class name, or a PHP callable
             $this->_definitions[$id] = $definition;//直接储存到_definitions中
         } elseif (is_array($definition)) {//如果传入的$definition是一个数组
             // a configuration array
             if (isset($definition['class'])) {//且数组中存在类名
                 $this->_definitions[$id] = $definition;//则将该数组储存到_definitions中
             } else {//否则，抛出异常
                 throw new InvalidConfigException("The configuration for the \"$id\" component must contain a \"class\" element.");
             }
         } else {//否则，抛出异常
             throw new InvalidConfigException("Unexpected configuration type for the \"$id\" component: " . gettype($definition));
         }
     }

     /**
      * Removes the component from the locator.
      * 删除一个服务或组件
      * @param string $id the component ID
      */
     public function clear($id)
     {
         unset($this->_definitions[$id], $this->_components[$id]);
     }

     /**
      * Returns the list of the component definitions or the loaded component instances.
      * 用于返回Service Locator的 $_components 数组或 $_definitions 数组，
      * 同时也是 components 属性的getter函数
      * @param boolean $returnDefinitions whether to return component definitions instead of the loaded component instances.
      * @return array the list of the component definitions or the loaded component instances (ID => definition or instance).
      */
     public function getComponents($returnDefinitions = true)
     {
         return $returnDefinitions ? $this->_definitions : $this->_components;
     }

     /**
      * Registers a set of component definitions in this locator.
      * 批量方式注册组件，同时也是 components 属性的setter函数
      * 其实就是以数组的方式传入set方法的参数，遍历后调用set
      *
      * This is the bulk version of [[set()]]. The parameter should be an array
      * whose keys are component IDs and values the corresponding component definitions.
      *
      * For more details on how to specify component IDs and definitions, please refer to [[set()]].
      *
      * If a component definition with the same ID already exists, it will be overwritten.
      *
      * The following is an example for registering two component definitions:
      *
      * ```php
      * [
      *     'db' => [
      *         'class' => 'yii\db\Connection',
      *         'dsn' => 'sqlite:path/to/file.db',
      *     ],
      *     'cache' => [
      *         'class' => 'yii\caching\DbCache',
      *         'db' => 'db',
      *     ],
      * ]
      * ```
      *
      * @param array $components component definitions or instances
      */
     public function setComponents($components)
     {
         foreach ($components as $id => $component) {
             $this->set($id, $component);
         }
     }
 }