ServiceLocator，服务定位类，用于yii2中的依赖注入，通过以ID为索引的方式缓存服务或则组件的实例来定位服务或者组件：
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);
}
}
}