Class yii\di\Instance

Inheritanceyii\di\Instance
Available since version2.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

PropertyTypeDescriptionDefined 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

MethodDescriptionDefined 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

MethodDescriptionDefined By
__construct() Constructor. yii\di\Instance

Property Details

$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

__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

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

Restores class state after using var_export().

See also var_export().

public static yii\di\Instance __set_state ( $state )
$state array
throws yii\base\InvalidConfigException

when $state property does not contain id parameter

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::className());
// returns an instance of Connection using the given configuration
$db = Instance::ensure(['dsn' => 'sqlite:path/to/my.db'], Connection::className());
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

The class/interface name to be checked. If null, type check will not be performed.

$container yii\di\ServiceLocator|yii\di\Container

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

get() public method

Returns the actual object referenced by this Instance object.

public object get ( $container null )
$container yii\di\ServiceLocator|yii\di\Container

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.

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.