# Class yii\di\Instance

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()`.

See also https://www.php.net/manual/en/function.var-export.php.

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);
    }