Class yii\di\Container

All Classes | Properties | Methods

Inheritance	yii\di\Container » yii\base\Component » yii\base\BaseObject
Implements	yii\base\Configurable
Available since version	2.0
Source Code	https://github.com/yiisoft/yii2/blob/master/framework/di/Container.php

Container implements a dependency injection container.

A dependency injection (DI) container is an object that knows how to instantiate and configure objects and all their dependent objects. For more information about DI, please refer to Martin Fowler's article.

Container supports constructor injection as well as property injection.

To use Container, you first need to set up the class dependencies by calling set(). You then call get() to create a new class object. The Container will automatically instantiate dependent objects, inject them into the object being created, configure, and finally return the newly created object.

By default, Yii::$container refers to a Container instance which is used by Yii::createObject() to create new object instances. You may use this method to replace the new operator when creating a new object, which gives you the benefit of automatic dependency resolution and default property configuration.

Below is an example of using 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');

// which is equivalent to:

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

For more details and usage information on Container, see the guide article on di-containers.

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
$behaviors	yii\base\Behavior[]	List of behaviors attached to this component.	yii\base\Component
$definitions	array	The list of the object definitions or the loaded shared objects (type or ID => definition or instance).	yii\di\Container
$resolveArrays	boolean	Whether to attempt to resolve elements in array dependencies.	yii\di\Container
$singleton	string	Class name, interface name or alias name	yii\di\Container
$singletons	array	Array of singleton definitions.	yii\di\Container

Public Methods

Hide inherited methods

Method	Description	Defined By
__call()	Calls the named method which is not a class method.	yii\base\Component
__clone()	This method is called after the object is created by cloning an existing one.	yii\base\Component
__construct()	Constructor.	yii\base\BaseObject
__get()	Returns the value of a component property.	yii\base\Component
__isset()	Checks if a property is set, i.e. defined and not null.	yii\base\Component
__set()	Sets the value of a component property.	yii\base\Component
__unset()	Sets a component property to be null.	yii\base\Component
attachBehavior()	Attaches a behavior to this component.	yii\base\Component
attachBehaviors()	Attaches a list of behaviors to the component.	yii\base\Component
behaviors()	Returns a list of behaviors that this component should behave as.	yii\base\Component
canGetProperty()	Returns a value indicating whether a property can be read.	yii\base\Component
canSetProperty()	Returns a value indicating whether a property can be set.	yii\base\Component
className()	Returns the fully qualified name of this class.	yii\base\BaseObject
clear()	Removes the definition for the specified name.	yii\di\Container
detachBehavior()	Detaches a behavior from the component.	yii\base\Component
detachBehaviors()	Detaches all behaviors from the component.	yii\base\Component
ensureBehaviors()	Makes sure that the behaviors declared in behaviors() are attached to this component.	yii\base\Component
get()	Returns an instance of the requested class.	yii\di\Container
getBehavior()	Returns the named behavior object.	yii\base\Component
getBehaviors()	Returns all behaviors attached to this component.	yii\base\Component
getDefinitions()	Returns the list of the object definitions or the loaded shared objects.	yii\di\Container
has()	Returns a value indicating whether the container has the definition of the specified name.	yii\di\Container
hasEventHandlers()	Returns a value indicating whether there is any handler attached to the named event.	yii\base\Component
hasMethod()	Returns a value indicating whether a method is defined.	yii\base\Component
hasProperty()	Returns a value indicating whether a property is defined for this component.	yii\base\Component
hasSingleton()	Returns a value indicating whether the given name corresponds to a registered singleton.	yii\di\Container
init()	Initializes the object.	yii\base\BaseObject
invoke()	Invoke a callback with resolving dependencies in parameters.	yii\di\Container
off()	Detaches an existing event handler from this component.	yii\base\Component
on()	Attaches an event handler to an event.	yii\base\Component
resolveCallableDependencies()	Resolve dependencies for a function.	yii\di\Container
set()	Registers a class definition with this container.	yii\di\Container
setDefinitions()	Registers class definitions within this container.	yii\di\Container
setResolveArrays()		yii\di\Container
setSingleton()	Registers a class definition with this container and marks the class as a singleton class.	yii\di\Container
setSingletons()	Registers class definitions as singletons within this container by calling setSingleton().	yii\di\Container
trigger()	Triggers an event.	yii\base\Component

Protected Methods

Hide inherited methods

Method	Description	Defined By
build()	Creates an instance of the specified class.	yii\di\Container
getDependencies()	Returns the dependencies of the specified class.	yii\di\Container
mergeParams()	Merges the user-specified constructor parameters with the ones registered via set().	yii\di\Container
normalizeDefinition()	Normalizes the class definition.	yii\di\Container
resolveDependencies()	Resolves dependencies by replacing them with the actual object instances.	yii\di\Container

Property Details

Hide inherited properties

$definitions public property

The list of the object definitions or the loaded shared objects (type or ID => definition or instance).

public array $definitions = null

$resolveArrays public property

Whether to attempt to resolve elements in array dependencies.

public boolean $resolveArrays = null

$singleton public write-only property

Class name, interface name or alias name

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

$singletons public write-only property (available since version 2.0.11)

Array of singleton definitions. See setDefinitions() for allowed formats of array.

public void setSingletons ( array $singletons )

Method Details

Hide inherited methods

__call() public method

Defined in: yii\base\Component::__call()

Calls the named method which is not a class method.

This method will check if any attached behavior has the named method and will execute it if available.

Do not call this method directly as it is a PHP magic method that will be implicitly called when an unknown method is being invoked.

public mixed __call ( $name, $params )
$name	string	The method name
$params	array	Method parameters
return	mixed	The method return value
throws	yii\base\UnknownMethodException	when calling unknown method

Source code

                public function __call($name, $params)
{
    $this->ensureBehaviors();
    foreach ($this->_behaviors as $object) {
        if ($object->hasMethod($name)) {
            return call_user_func_array([$object, $name], $params);
        }
    }
    throw new UnknownMethodException('Calling unknown method: ' . get_class($this) . "::$name()");
}

__clone() public method

Defined in: yii\base\Component::__clone()

This method is called after the object is created by cloning an existing one.

It removes all behaviors because they are attached to the old object.

public void __clone ( )

Source code

                public function __clone()
{
    $this->_events = [];
    $this->_eventWildcards = [];
    $this->_behaviors = null;
}

__construct() public method

Defined in: yii\base\BaseObject::__construct()

Constructor.

The default implementation does two things:

Initializes the object with the given configuration $config.
Call init().

If this method is overridden in a child class, it is recommended that

the last parameter of the constructor is a configuration array, like $config here.
call the parent implementation at the end of the constructor.

public void __construct ( $config = [] )
$config	array	Name-value pairs that will be used to initialize the object properties

Source code

                public function __construct($config = [])
{
    if (!empty($config)) {
        Yii::configure($this, $config);
    }
    $this->init();
}

__get() public method

Defined in: yii\base\Component::__get()

Returns the value of a component property.

This method will check in the following order and act accordingly:

a property defined by a getter: return the getter result
a property of a behavior: return the behavior property value

Do not call this method directly as it is a PHP magic method that will be implicitly called when executing $value = $component->property;.

public mixed __get ( $name )
$name	string	The property name
return	mixed	The property value or the value of a behavior's property
throws	yii\base\UnknownPropertyException	if the property is not defined
throws	yii\base\InvalidCallException	if the property is write-only.

public boolean __isset ( $name )
$name	string	The property name or the event name
return	boolean	Whether the named property is set

public void __set ( $name, $value )
$name	string	The property name or the event name
$value	mixed	The property value
throws	yii\base\UnknownPropertyException	if the property is not defined
throws	yii\base\InvalidCallException	if the property is read-only.

public void __unset ( $name )
$name	string	The property name
throws	yii\base\InvalidCallException	if the property is read only.

public yii\base\Behavior attachBehavior ( $name, $behavior )
$name	string	The name of the behavior.
$behavior	string\|array\|yii\base\Behavior	The behavior configuration. This can be one of the following: a yii\base\Behavior object a string specifying the behavior class an object configuration array that will be passed to Yii::createObject() to create the behavior object.
return	yii\base\Behavior	The behavior object

public array behaviors ( )
return	array	The behavior configurations.

protected object build ( $class, $params, $config )
$class	string	The class name
$params	array	Constructor parameters
$config	array	Configurations to be applied to the new instance
return	object	The newly created instance of the specified class
throws	yii\di\NotInstantiableException	If resolved to an abstract class or an interface (since 2.0.9)

public boolean canGetProperty ( $name, $checkVars = true, $checkBehaviors = true )
$name	string	The property name
$checkVars	boolean	Whether to treat member variables as properties
$checkBehaviors	boolean	Whether to treat behaviors' properties as properties of this component
return	boolean	Whether the property can be read

public boolean canSetProperty ( $name, $checkVars = true, $checkBehaviors = true )
$name	string	The property name
$checkVars	boolean	Whether to treat member variables as properties
$checkBehaviors	boolean	Whether to treat behaviors' properties as properties of this component
return	boolean	Whether the property can be written

public static string className ( )
return	string	The fully qualified name of this class.

public yii\base\Behavior\|null detachBehavior ( $name )
$name	string	The behavior's name.
return	yii\base\Behavior\|null	The detached behavior. Null if the behavior does not exist.

public object get ( $class, $params = [], $config = [] )
$class	string\|yii\di\Instance	The class Instance, name, or an alias name (e.g. `foo`) that was previously registered via set() or setSingleton().
$params	array	A list of constructor parameter values. Use one of two definitions: Parameters as name-value pairs, for example: `['posts' => PostRepository::class]`. Parameters in the order they appear in the constructor declaration. If you want to skip some parameters, you should index the remaining ones with the integers that represent their positions in the constructor parameter list. Dependencies indexed by name and by position in the same array are not allowed.
$config	array	A list of name-value pairs that will be used to initialize the object properties.
return	object	An instance of the requested class.
throws	yii\base\InvalidConfigException	if the class cannot be recognized or correspond to an invalid definition
throws	yii\di\NotInstantiableException	If resolved to an abstract class or an interface (since 2.0.9)

public yii\base\Behavior\|null getBehavior ( $name )
$name	string	The behavior name
return	yii\base\Behavior\|null	The behavior object, or null if the behavior does not exist

public yii\base\Behavior[] getBehaviors ( )
return	yii\base\Behavior[]	List of behaviors attached to this component

public array getDefinitions ( )
return	array	The list of the object definitions or the loaded shared objects (type or ID => definition or instance).

protected array getDependencies ( $class )
$class	string	Class name, interface name or alias name
return	array	The dependencies of the specified class.
throws	yii\di\NotInstantiableException	if a dependency cannot be resolved or if a dependency cannot be fulfilled.

public boolean has ( $class )
$class	string	Class name, interface name or alias name
return	boolean	Whether the container has the definition of the specified name.

public boolean hasEventHandlers ( $name )
$name	string	The event name
return	boolean	Whether there is any handler attached to the event.

public boolean hasMethod ( $name, $checkBehaviors = true )
$name	string	The property name
$checkBehaviors	boolean	Whether to treat behaviors' methods as methods of this component
return	boolean	Whether the method is defined

public boolean hasProperty ( $name, $checkVars = true, $checkBehaviors = true )
$name	string	The property name
$checkVars	boolean	Whether to treat member variables as properties
$checkBehaviors	boolean	Whether to treat behaviors' properties as properties of this component
return	boolean	Whether the property is defined

public boolean hasSingleton ( $class, $checkInstance = false )
$class	string	Class name, interface name or alias name
$checkInstance	boolean	Whether to check if the singleton has been instantiated.
return	boolean	Whether the given name corresponds to a registered singleton. If `$checkInstance` is true, the method should return a value indicating whether the singleton has been instantiated.

public mixed invoke ( callable $callback, $params = [] )
$callback	callable	Callable to be invoked.
$params	array	The array of parameters for the function. This can be either a list of parameters, or an associative array representing named function parameters.
return	mixed	The callback return value.
throws	yii\base\InvalidConfigException	if a dependency cannot be resolved or if a dependency cannot be fulfilled.
throws	yii\di\NotInstantiableException	If resolved to an abstract class or an interface (since 2.0.9)

protected array mergeParams ( $class, $params )
$class	string	Class name, interface name or alias name
$params	array	The constructor parameters
return	array	The merged parameters

protected array normalizeDefinition ( $class, $definition )
$class	string	Class name
$definition	string\|array\|callable	The class definition
return	array	The normalized class definition
throws	yii\base\InvalidConfigException	if the definition is invalid.

public boolean off ( $name, $handler = null )
$name	string	Event name
$handler	callable\|null	The event handler to be removed. If it is null, all handlers attached to the named event will be removed.
return	boolean	If a handler is found and detached

See also off().

public void on ( $name, $handler, $data = null, $append = true )
$name	string	The event name
$handler	callable	The event handler
$data	mixed	The data to be passed to the event handler when the event is triggered. When the event handler is invoked, this data can be accessed via yii\base\Event::$data.
$append	boolean	Whether to append new event handler to the end of the existing handler list. If false, the new handler will be inserted at the beginning of the existing handler list.

Source code

                public function on($name, $handler, $data = null, $append = true)
{
    $this->ensureBehaviors();
    if (strpos($name, '*') !== false) {
        if ($append || empty($this->_eventWildcards[$name])) {
            $this->_eventWildcards[$name][] = [$handler, $data];
        } else {
            array_unshift($this->_eventWildcards[$name], [$handler, $data]);
        }
        return;
    }
    if ($append || empty($this->_events[$name])) {
        $this->_events[$name][] = [$handler, $data];
    } else {
        array_unshift($this->_events[$name], [$handler, $data]);
    }
}

resolveCallableDependencies() public method (available since version 2.0.7)

Resolve dependencies for a function.

This method can be used to implement similar functionality as provided by invoke() in other components.

public array resolveCallableDependencies ( callable $callback, $params = [] )
$callback	callable	Callable to be invoked.
$params	array	The array of parameters for the function, can be either numeric or associative.
return	array	The resolved dependencies.
throws	yii\base\InvalidConfigException	if a dependency cannot be resolved or if a dependency cannot be fulfilled.
throws	yii\di\NotInstantiableException	If resolved to an abstract class or an interface (since 2.0.9)

Source code

                public function resolveCallableDependencies(callable $callback, $params = [])
{
    if (is_array($callback)) {
        $reflection = new \ReflectionMethod($callback[0], $callback[1]);
    } elseif (is_object($callback) && !$callback instanceof \Closure) {
        $reflection = new \ReflectionMethod($callback, '__invoke');
    } else {
        $reflection = new \ReflectionFunction($callback);
    }
    $args = [];
    $associative = ArrayHelper::isAssociative($params);
    foreach ($reflection->getParameters() as $param) {
        $name = $param->getName();
        if (PHP_VERSION_ID >= 80000) {
            $class = $param->getType();
            if ($class instanceof \ReflectionUnionType || (PHP_VERSION_ID >= 80100 && $class instanceof \ReflectionIntersectionType)) {
                $isClass = false;
                foreach ($class->getTypes() as $type) {
                    if (!$type->isBuiltin()) {
                        $class = $type;
                        $isClass = true;
                        break;
                    }
                }
            } else {
                $isClass = $class !== null && !$class->isBuiltin();
            }
        } else {
            $class = $param->getClass();
            $isClass = $class !== null;
        }
        if ($isClass) {
            $className = $class->getName();
            if (PHP_VERSION_ID >= 50600 && $param->isVariadic()) {
                $args = array_merge($args, array_values($params));
                break;
            }
            if ($associative && isset($params[$name]) && $params[$name] instanceof $className) {
                $args[] = $params[$name];
                unset($params[$name]);
            } elseif (!$associative && isset($params[0]) && $params[0] instanceof $className) {
                $args[] = array_shift($params);
            } elseif (isset(Yii::$app) && Yii::$app->has($name) && ($obj = Yii::$app->get($name)) instanceof $className) {
                $args[] = $obj;
            } else {
                // If the argument is optional we catch not instantiable exceptions
                try {
                    $args[] = $this->get($className);
                } catch (NotInstantiableException $e) {
                    if ($param->isDefaultValueAvailable()) {
                        $args[] = $param->getDefaultValue();
                    } else {
                        throw $e;
                    }
                }
            }
        } elseif ($associative && isset($params[$name])) {
            $args[] = $params[$name];
            unset($params[$name]);
        } elseif (!$associative && count($params)) {
            $args[] = array_shift($params);
        } elseif ($param->isDefaultValueAvailable()) {
            $args[] = $param->getDefaultValue();
        } elseif (!$param->isOptional()) {
            $funcName = $reflection->getName();
            throw new InvalidConfigException("Missing required parameter \"$name\" when calling \"$funcName\".");
        }
    }
    foreach ($params as $value) {
        $args[] = $value;
    }
    return $args;
}

resolveDependencies() protected method

Resolves dependencies by replacing them with the actual object instances.

protected array resolveDependencies ( $dependencies, $reflection = null )
$dependencies	array	The dependencies
$reflection	ReflectionClass\|null	The class reflection associated with the dependencies
return	array	The resolved dependencies
throws	yii\base\InvalidConfigException	if a dependency cannot be resolved or if a dependency cannot be fulfilled.

Source code

                protected function resolveDependencies($dependencies, $reflection = null)
{
    foreach ($dependencies as $index => $dependency) {
        if ($dependency instanceof Instance) {
            if ($dependency->id !== null) {
                $dependencies[$index] = $dependency->get($this);
            } elseif ($reflection !== null) {
                $name = $reflection->getConstructor()->getParameters()[$index]->getName();
                $class = $reflection->getName();
                throw new InvalidConfigException("Missing required parameter \"$name\" when instantiating \"$class\".");
            }
        } elseif ($this->_resolveArrays && is_array($dependency)) {
            $dependencies[$index] = $this->resolveDependencies($dependency, $reflection);
        }
    }
    return $dependencies;
}

set() public method

Registers a class definition with this container.

For example,

// register a class name as is. This can be skipped.
$container->set('yii\db\Connection');

// register an interface
// When a class depends on the interface, the corresponding class
// will be instantiated as the dependent object
$container->set('yii\mail\MailInterface', 'yii\swiftmailer\Mailer');

// register an alias name. You can use $container->get('foo')
// to create an instance of Connection
$container->set('foo', 'yii\db\Connection');

// register a class with configuration. The configuration
// will be applied when the class is instantiated by get()
$container->set('yii\db\Connection', [
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
]);

// register an alias name with class configuration
// In this case, a "class" element is required to specify the class
$container->set('db', [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=127.0.0.1;dbname=demo',
    'username' => 'root',
    'password' => '',
    'charset' => 'utf8',
]);

// register a PHP callable
// The callable will be executed when $container->get('db') is called
$container->set('db', function ($container, $params, $config) {
    return new \yii\db\Connection($config);
});

If a class definition with the same name already exists, it will be overwritten with the new one. You may use has() to check if a class definition already exists.

public $this set ( $class, $definition = [], array $params = [] )
$class	string	Class name, interface name or alias name
$definition	mixed	The definition associated with `$class`. It can be one of the following: a PHP callable: The callable will be executed when get() is invoked. The signature of the callable should be `function ($container, $params, $config)`, where `$params` stands for the list of constructor parameters, `$config` the object configuration, and `$container` the container object. The return value of the callable will be returned by get() as the object instance requested. 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 stands for the class of the object to be created. If `class` is not specified, `$class` will be used as the class name. a string: a class name, an interface name or an alias name.
$params	array	The list of constructor parameters. The parameters will be passed to the class constructor when get() is called.
return	$this	The container itself

Source code

                public function set($class, $definition = [], array $params = [])
{
    $this->_definitions[$class] = $this->normalizeDefinition($class, $definition);
    $this->_params[$class] = $params;
    unset($this->_singletons[$class]);
    return $this;
}

setDefinitions() public method (available since version 2.0.11)

Registers class definitions within this container.

See also set() to know more about possible values of definitions.

public void setDefinitions ( array $definitions )
$definitions	array	Array of definitions. There are two allowed formats of array. The first format: key: class name, interface name or alias name. The key will be passed to the set() method as a first argument `$class`. value: the definition associated with `$class`. Possible values are described in set() documentation for the `$definition` parameter. Will be passed to the set() method as the second argument `$definition`. Example: `php $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); }` ]); ` The second format: key: class name, interface name or alias name. The key will be passed to the set() method as a first argument `$class`. value: array of two elements. The first element will be passed the set() method as the second argument `$definition`, the second one — as `$params`. Example: `php $container->setDefinitions([ `'foo\Bar' => [ ['class' => 'app\Bar'], [Instance::of('baz')] ]` ]); `

Source code

                public function setDefinitions(array $definitions)
{
    foreach ($definitions as $class => $definition) {
        if (is_array($definition) && count($definition) === 2 && array_values($definition) === $definition && is_array($definition[1])) {
            $this->set($class, $definition[0], $definition[1]);
            continue;
        }
        $this->set($class, $definition);
    }
}

setResolveArrays() public method (available since version 2.0.37)

public void setResolveArrays ( $value )
$value	boolean	Whether to attempt to resolve elements in array dependencies

Source code

                public function setResolveArrays($value)
{
    $this->_resolveArrays = (bool) $value;
}

setSingleton() public method

Registers a class definition with this container and marks the class as a singleton class.

This method is similar to set() except that classes registered via this method will only have one instance. Each time get() is called, the same instance of the specified class will be returned.

public void trigger ( $name, yii\base\Event $event = null )
$name	string	The event name
$event	yii\base\Event\|null	The event instance. If not set, a default yii\base\Event object will be created.

public void attachBehaviors ( $behaviors )
$behaviors	array	List of behaviors to be attached to the component

public void clear ( $class )
$class	string	Class name, interface name or alias name