Class yii\di\Container

继承yii\di\Container » yii\base\Component » yii\base\BaseObject
实现yii\base\Configurable
可用自版本2.0
源代码 https://github.com/yiisoft/yii2/blob/master/framework/di/Container.php

容器(Container)实现 依赖注入 容器.

依赖项注入(DI)容器是指定如何实例化和配置对象及其所有依赖对象的对象. 有关 ID 的更多信息, 请参阅 Martin Fowler's article.

容器(Container)支持构造函数注入以及属性注入.

要使用容器(Container), 首先需要通过调用 set() 来设置类依赖关系. 然后调用 get() 创建一个新的类对象. 容器(Container)将自动实例化相关对象, 将它们注入到正在创建的对象中, 进行配置并最终返回新创建的对象.

默认情况下, Yii::$container 指的是一个容器(Container)实例, Yii::createObject() 使用它来创建新的对象实例. 在创建新对象时, 你可以使用此方法替换new运算符, 从而为你带来自动依赖关系解析和默认属性配置的好处.

以下是使用容器(Container)的示例:

namespace app\models;

use yii\base\BaseObject;
use yii\db\Connection;
use yii\di\Container;

interface UserFinderInterface
{
    function findUser();
}

class UserFinder extends BaseObject implements UserFinderInterface
{
    public $db;

    public function __construct(Connection $db, $config = [])
    {
        $this->db = $db;
        parent::__construct($config);
    }

    public function findUser()
    {
    }
}

class UserLister extends BaseObject
{
    public $finder;

    public function __construct(UserFinderInterface $finder, $config = [])
    {
        $this->finder = $finder;
        parent::__construct($config);
    }
}

$container = new Container;
$container->set('yii\db\Connection', [
    'dsn' => '...',
]);
$container->set('app\models\UserFinderInterface', [
    'class' => 'app\models\UserFinder',
]);
$container->set('userLister', 'app\models\UserLister');

$lister = $container->get('userLister');

// 等效于:

$db = new \yii\db\Connection(['dsn' => '...']);
$finder = new UserFinder($db);
$lister = new UserLister($finder);

有关 Container 的更多详细信息和使用信息, 请参阅 权威指南 - 关键概念 - 依赖注入容器(Dependency Injection Container).

公共属性

隐藏继承的属性

属性类型描述定义在
$behaviors yii\base\Behavior[] 附加到此组件的行为列表. 该属性是只读的. yii\base\Component
$definitions array 对象定义列表或已加载的共享对象(type or ID => definition or instance). 该属性是只读的. yii\di\Container
$resolveArrays boolean 是否尝试解析数组依赖项中的元素. 该属性是只写的. yii\di\Container
$singleton string 类名, 接口名称或别名. yii\di\Container
$singletons array 单例定义的数组. yii\di\Container

公共方法

隐藏继承的方法

方法描述定义在
__call() 调用不是类方法的指定的方法. yii\base\Component
__clone() 在通过克隆现有对象创建对象之后调用此方法. yii\base\Component
__construct() 构造函数. yii\base\BaseObject
__get() 返回组件属性的值. yii\base\Component
__isset() 检查属性是否已设置, 即已定义且不为null. yii\base\Component
__set() 设置组件属性的值. yii\base\Component
__unset() 将组件属性设置为null. yii\base\Component
attachBehavior() 将行为附加到此组件. yii\base\Component
attachBehaviors() 将行为列表附加到组件. yii\base\Component
behaviors() 返回此组件应该具有的行为列表. yii\base\Component
canGetProperty() 返回一个值, 指示属性是否可读取. yii\base\Component
canSetProperty() 返回一个值, 指示属性是否可设置. yii\base\Component
className() 返回此类的完全限定名称. yii\base\BaseObject
clear() 删除指定名称的定义. yii\di\Container
detachBehavior() 从组件中分离一个行为. yii\base\Component
detachBehaviors() 分离组件中的所有行为. yii\base\Component
ensureBehaviors() 确保在 behaviors() 中声明的行为已附加到此组件. yii\base\Component
get() 返回所请求类的实例. yii\di\Container
getBehavior() 返回指定的行为对象. yii\base\Component
getBehaviors() 返回附加到此组件的所有行为. yii\base\Component
getDefinitions() 返回对象定义列表或已加载的共享对象. yii\di\Container
has() 返回一个值, 该值指示容器是否具有指定名称的定义. yii\di\Container
hasEventHandlers() 返回一个值, 指示是否有任何处理程序附加到指定的事件. yii\base\Component
hasMethod() 返回一个值, 指示方法是否已定义. yii\base\Component
hasProperty() 返回一个值, 指示属性是否已定义. yii\base\Component
hasSingleton() 返回一个值, 该值指示给定名称是否对应于注册的单例. yii\di\Container
init() 初始化对象. yii\base\BaseObject
invoke() 通过解析参数中的依赖关系来调用回调. yii\di\Container
off() 从该组件分离现有的事件处理程序. yii\base\Component
on() 将事件处理程序附加到事件. yii\base\Component
resolveCallableDependencies() 解决函数的依赖关系. yii\di\Container
set() 在此容器中注册一个类定义. yii\di\Container
setDefinitions() 在此容器中注册类定义. yii\di\Container
setResolveArrays() yii\di\Container
setSingleton() 在此容器中注册一个类定义, 并将该类标记为单例类. yii\di\Container
setSingletons() 通过调用 setSingleton() 在该容器中将类定义注册为单例. yii\di\Container
trigger() 触发事件. yii\base\Component

受保护的方法

隐藏继承的方法

方法描述定义在
build() 创建指定类的实例. yii\di\Container
getDependencies() 返回指定类的依赖关系. yii\di\Container
mergeParams() 将用户指定的构造函数参数与通过 set() 注册的参数合并. yii\di\Container
normalizeDefinition() 规范类定义. yii\di\Container
resolveDependencies() 通过将依赖关系替换为实际的对象实例来解决依赖关系. yii\di\Container

属性详情

$definitions public 属性

对象定义列表或已加载的共享对象(type or ID => definition or instance). 该属性是只读的.

public array $definitions null
$resolveArrays public 属性

是否尝试解析数组依赖项中的元素. 该属性是只写的.

public boolean $resolveArrays null
$singleton public 只写 属性

类名, 接口名称或别名.

public $this setSingleton ( $class, $definition = [], array $params = [] )
$singletons public 只写 属性 (可用自版本: 2.0.11)

单例定义的数组. 有关允许的数组格式,请参阅 setDefinitions().

public void setSingletons ( array $singletons )

方法详情

build() protected 方法

创建指定类的实例.

此方法将解析指定类的依赖项, 实例化它们, 并将其注入到指定类的新实例中.

protected object build ( $class, $params, $config )
$class string

类名.

$params array

构造函数参数.

$config array

要应用于新实例的配置.

return object

指定类的新创建实例.

throws yii\di\NotInstantiableException

如果解析为抽象类或接口(自 2.0.9 开始).

clear() public 方法

删除指定名称的定义.

public void clear ( $class )
$class string

类名, 接口名称或别名.

get() public 方法

返回所请求类的实例.

你可以提供在实例创建期间将使用的构造函数参数($params)和对象配置($config).

如果类实现了 yii\base\Configurable, 则$config参数将作为最后一个参数传递给类构造函数; 否则, 将在实例化对象之应用配置.

Note: 如果通过调用 setSingleton() 将类声明为单例, 则每次调用此方法时, 都将返回该类的相同实例. 在这种情况下, 仅当首次实例化该类时, 才使用构造函数参数和对象配置.

public object get ( $class, $params = [], $config = [] )
$class string|yii\di\Instance

类实例, 类名称或之前通过 set()setSingleton() 注册的别名(eg. foo)。

$params array

构造函数参数值的列表. 使用以下两个定义之一:

  • 参数为name-value对, 例如: ['posts' => PostRepository::class].
  • 参数按照它们在构造函数声明中出现的顺序排列. 如果要跳过某些参数, 则应使用代表它们在构造函数参数列表中位置的整数来索引其余的参数. 不允许按名称和按位置索引在同一数组中的依赖项.

应该按照在构造函数声明中出现的顺序提供参数. 如果要跳过某些参数, 则应使用代表它们在构造函数参数列表中位置的整数类索引其余的参数.

$config array

用来初始化对象属性的 name-value 列表.

return object

所请求类的实例.

throws yii\base\InvalidConfigException

如果无法识别类或对应于无效的定义.

throws yii\di\NotInstantiableException

如果解析为抽象类或接口(自 2.0.9 开始).

getDefinitions() public 方法

返回对象定义列表或已加载的共享对象.

public array getDefinitions ( )
return array

对象定义列表或已加载的共享对象(type or ID => definition or instance).

getDependencies() protected 方法

返回指定类的依赖关系.

protected array getDependencies ( $class )
$class string

类名, 接口名称或别名.

return array

指定类的依赖项.

throws yii\di\NotInstantiableException

如果无法解决依赖关系或无法满足依赖关系.

has() public 方法

返回一个值, 该值指示容器是否具有指定名称的定义.

参见 set().

public boolean has ( $class )
$class string

类名, 接口名称或别名.

return boolean

容器是否具有指定名称的定义.

hasSingleton() public 方法

返回一个值, 该值指示给定名称是否对应于注册的单例.

public boolean hasSingleton ( $class, $checkInstance false )
$class string

类名, 接口名称或别名.

$checkInstance boolean

是否检查单例是否已实例化.

return boolean

给定名称是否对应于注册的单例. 如果$checkInstancetrue, 则该方法应返回一个值, 该值指示是否已实例化单例.

invoke() public 方法 (可用自版本: 2.0.7)

通过解析参数中的依赖关系来调用回调.

此方法允许调用回调, 并将类型提示的参数名称解析为 Container 的对象. 它还允许使用命名参数调用函数.

例如, 可以使用 Container 来调用以下回调来解析格式化程序依赖性:

$formatString = function($string, \yii\i18n\Formatter $formatter) {
   // ...
}
Yii::$container->invoke($formatString, ['string' => 'Hello World!']);

这将传递字符串Hello World!作为第一个参数, 并将由 DI 容器创建的格式化程序实例作为第二个参数传递给可调用对象.

public mixed invoke ( callable $callback, $params = [] )
$callback callable

被调用的回调函数.

$params array

该函数的参数数组. 这可以是参数列表, 也可以是代表命名函数参数的关联数组.

return mixed

回调函数的返回值.

throws yii\base\InvalidConfigException

如果无法解决依赖关系或无法满足依赖关系.

throws yii\di\NotInstantiableException

如果解析为抽象类或接口(自 2.0.9 开始).

mergeParams() protected 方法

将用户指定的构造函数参数与通过 set() 注册的参数合并.

protected array mergeParams ( $class, $params )
$class string

类名, 接口名称或别名.

$params array

构造函数参数.

return array

合并参数.

normalizeDefinition() protected 方法

规范类定义.

protected array normalizeDefinition ( $class, $definition )
$class string

类名.

$definition string|array|callable

类定义.

return array

标准化的类定义.

throws yii\base\InvalidConfigException

如果定义无效.

resolveCallableDependencies() public 方法 (可用自版本: 2.0.7)

解决函数的依赖关系.

此方法可用于实现与 invoke() 在其它组件中提供的功能类似的功能.

public array resolveCallableDependencies ( callable $callback, $params = [] )
$callback callable

被调用的回调函数.

$params array

该函数的参数数组可以是数字或关联的.

return array

解决的依赖关系.

throws yii\base\InvalidConfigException

如果无法解决依赖关系或无法满足依赖关系.

throws yii\di\NotInstantiableException

如果解析为抽象类或接口(自 2.0.9 开始)

resolveDependencies() protected 方法

通过将依赖关系替换为实际的对象实例来解决依赖关系.

protected array resolveDependencies ( $dependencies, $reflection null )
$dependencies array

依赖.

$reflection ReflectionClass

与依赖关系相关的类反射.

return array

解决的依赖关系.

throws yii\base\InvalidConfigException

如果无法解决依赖关系或无法满足依赖关系.

set() public 方法

在此容器中注册一个类定义.

例如:

// 按原样注册一个类名. 可以跳过.
$container->set('yii\db\Connection');

// 注册接口当一个类依赖于该接口时, 对应的类将被实例化为依赖对象.
$container->set('yii\mail\MailInterface', 'yii\swiftmailer\Mailer');

// 注册一个别名. 你可以使用 $container->get('foo') 创建连接(Connection)的实例.
$container->set('foo', 'yii\db\Connection');

// 使用配置注册一个类. 当通过 get() 实例化该类时, 将应用该配置
$container->set('yii\db\Connection', [
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
]);

// 使用类配置注册别名
// 在这种情况下, 需要使用"class"元素来指定类名
$container->set('db', [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
]);

// 注册一个 PHP 回调
// 调用 $container->get('db') 时将执行可回调对象
$container->set('db', function ($container, $params, $config) {
    return new \yii\db\Connection($config);
});

如果已经存在同名的类定义, 则它将被新的类定义覆盖. 你可以使用 has() 检查类定义是否已经存在.

public $this set ( $class, $definition = [], array $params = [] )
$class string

类名, 接口名称或别名.

$definition mixed

$class相关的定义. 可以是以下之一:

  • a PHP 回调: 调用 get() 时将执行可调用对象. 可调用对象的签名应为function ($container, $params, $config), 其中$params表示构造函数参数列表, $config是对象配置, $container是容器对象. 可调用对象的返回值将由 get() 作为请求的对象实例返回.
  • a 配置数组: 数组包含 name-value 对, 将在调用 get() 时用于初始化新创建的对象的属性值. class元素代表要创建的对象的类. 如果未指定class, 则将$class用作类名.
  • a string: 类名, 接口名称或别名.
$params array

构造函数参数列表. 调用 get() 时, 会将参数传递给类构造函数.

return $this

容器本身.

setDefinitions() public 方法 (可用自版本: 2.0.11)

在此容器中注册类定义.

参见 set() 进一步了解定义的可能值.

public void setDefinitions ( array $definitions )
$definitions array

定义数组. 有两种允许的数组格式.

第一种格式:

  • key: 类名, 接口名称或别名. 该键将作为第一个参数$class传递给 set() 方法.
  • value: 与$class关联的定义. $definition参数的 set() 文档中描述了可能的值. 将作为第二个参数$definition传递给 set() 方法.

例如:

$container->setDefinitions([
    'yii\web\Request' => 'app\components\Request',
    'yii\web\Response' => [
        'class' => 'app\components\Response',
        'format' => 'json'
    ],
    'foo\Bar' => function () {
        $qux = new Qux;
        $foo = new Foo($qux);
        return new Bar($foo);
    }
]);

第二种格式:

  • key: 类名, 接口名称或别名. 该键将作为第一个参数$class传递给 set() 方法.
  • value: 两个元素组成的数组. 第一个元素将作为第二个参数$definition, 第二个元素作为$params, 传递给 set() 方法.

例如:

$container->setDefinitions([
    'foo\Bar' => [
         ['class' => 'app\Bar'],
         [Instance::of('baz')]
     ]
]);
setResolveArrays() public 方法 (可用自版本: 2.0.37)

public void setResolveArrays ( $value )
$value boolean

是否尝试解析数组依赖项中的元素.

setSingleton() public 方法

在此容器中注册一个类定义, 并将该类标记为单例类.

此方法类似于 set(), 但通过此方法注册的类仅具有一个单例. 每次调用 get() 时, 将返回指定类的相同实例.

参见 set().

public $this setSingleton ( $class, $definition = [], array $params = [] )
$class string

类名, 接口名称或别名.

$definition mixed

$class相关的定义. 有关更多详细信息, 请参见 set().

$params array

构造函数参数列表. 调用 get() 时, 会将参数传递给类构造函数.

return $this

容器本身.

setSingletons() public 方法 (可用自版本: 2.0.11)

通过调用 setSingleton() 在该容器中将类定义注册为单例.

参见:

public void setSingletons ( array $singletons )
$singletons array

单例定义的数组. 有关允许的数组格式,请参阅 setDefinitions().