Class yii\di\Instance

All Classes | Properties | Methods

Inheritance	yii\di\Instance
Available since version	2.0
Source Code	https://github.com/yiisoft/yii2/blob/master/framework/di/Instance.php

Instance represents a reference to a named object in a dependency injection (DI) container or a service locator.

You may use get() to obtain the actual object referenced by $id.

Instance is mainly used in two places:

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.
In classes which use service locator to obtain dependent objects.

The following example shows how to configure a DI container with Instance:

$container = new \yii\di\Container;
$container->set('cache', [
    'class' => 'yii\caching\DbCache',
    'db' => 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:

class DbCache extends Cache
{
    public $db = 'db';

    public function init()
    {
        parent::init();
        $this->db = Instance::ensure($this->db, 'yii\db\Connection');
    }
}

Public Properties

Hide inherited properties

Property	Type	Description	Defined By
$id	string	The component ID, class name, interface name or alias name	yii\di\Instance
$optional	boolean	If null should be returned instead of throwing an exception	yii\di\Instance

Public Methods

Hide inherited methods

Method	Description	Defined By
__set_state()	Restores class state after using `var_export()`.	yii\di\Instance
ensure()	Resolves the specified reference into the actual object and makes sure it is of the specified type.	yii\di\Instance
get()	Returns the actual object referenced by this Instance object.	yii\di\Instance
of()	Creates a new Instance object.	yii\di\Instance

Protected Methods

Hide inherited methods

Method	Description	Defined By
__construct()	Constructor.	yii\di\Instance

Property Details

Hide inherited properties

$id public property

The component ID, class name, interface name or alias name

public string $id = null

$optional public property

If null should be returned instead of throwing an exception

public boolean $optional = null

Method Details

Hide inherited methods

__construct() protected method

Constructor.

protected void __construct ( $id, $optional = false )
$id	string	The component ID
$optional	boolean	If null should be returned instead of throwing an exception

Source code

                protected function __construct($id, $optional = false)
{
    $this->id = $id;
    $this->optional = $optional;
}

__set_state() public static method (available since version 2.0.12)

Restores class state after using var_export().

public static yii\di\Instance __set_state ( $state )
$state	array
throws	yii\base\InvalidConfigException	when $state property does not contain `id` parameter

Source code

                public static function __set_state($state)
{
    if (!isset($state['id'])) {
        throw new InvalidConfigException('Failed to instantiate class "Instance". Required parameter "id" is missing');
    }
    return new self($state['id']);
}

ensure() public static method

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,

use yii\db\Connection;

// returns Yii::$app->db
$db = Instance::ensure('db', Connection::class);
// returns an instance of Connection using the given configuration
$db = Instance::ensure(['dsn' => 'sqlite:path/to/my.db'], Connection::class);

public static object ensure ( $reference, $type = null, $container = null )
$reference	object\|string\|array\|static	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`.
$type	string\|null	The class/interface name to be checked. If null, type check will not be performed.
$container	yii\di\ServiceLocator\|yii\di\Container\|null	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	yii\base\InvalidConfigException	if the reference is invalid

Source code

                public static function ensure($reference, $type = null, $container = null)
{
    if (is_array($reference)) {
        $class = isset($reference['class']) ? $reference['class'] : $type;
        if (!$container instanceof Container) {
            $container = Yii::$container;
        }
        unset($reference['class']);
        $component = $container->get($class, [], $reference);
        if ($type === null || $component instanceof $type) {
            return $component;
        }
        throw new InvalidConfigException('Invalid data type: ' . $class . '. ' . $type . ' is expected.');
    } elseif (empty($reference)) {
        throw new InvalidConfigException('The required component is not specified.');
    }
    if (is_string($reference)) {
        $reference = new static($reference);
    } elseif ($type === null || $reference instanceof $type) {
        return $reference;
    }
    if ($reference instanceof self) {
        try {
            $component = $reference->get($container);
        } catch (\ReflectionException $e) {
            throw new InvalidConfigException('Failed to instantiate component or class "' . $reference->id . '".', 0, $e);
        }
        if ($type === null || $component instanceof $type) {
            return $component;
        }
        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.");
}

get() public method

Returns the actual object referenced by this Instance object.

public object get ( $container = null )
$container	yii\di\ServiceLocator\|yii\di\Container\|null	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.

Source code

                public function get($container = null)
{
    try {
        if ($container) {
            return $container->get($this->id);
        }
        if (Yii::$app && Yii::$app->has($this->id)) {
            return Yii::$app->get($this->id);
        }
        return Yii::$container->get($this->id);
    } catch (\Exception $e) {
        if ($this->optional) {
            return null;
        }
        throw $e;
    } catch (\Throwable $e) {
        if ($this->optional) {
            return null;
        }
        throw $e;
    }
}

of() public static method

Creates a new Instance object.

public static yii\di\Instance of ( $id, $optional = false )
$id	string	The component ID
$optional	boolean	If null should be returned instead of throwing an exception
return	yii\di\Instance	The new Instance object.

Source code

                public static function of($id, $optional = false)
{
    return new static($id, $optional);
}