0 follower

Class yii\di\Instance

All Classes | Properties | Methods
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

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

 

                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

 

                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

 

                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.

 

                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.

 

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