HumHub Documentation (unofficial)

Instance
in package

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');
    }
}
Tags
author

Qiang Xue qiang.xue@gmail.com

since
2.0

Table of Contents

Properties

$id  : string
$optional  : bool

Methods

__set_state()  : Instance
Restores class state after using `var_export()`.
ensure()  : object
Resolves the specified reference into the actual object and makes sure it is of the specified type.
get()  : object
Returns the actual object referenced by this Instance object.
of()  : Instance
Creates a new Instance object.
__construct()  : mixed
Constructor.

Properties

$id

public string $id

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

$optional

public bool $optional

if null should be returned instead of throwing an exception

Methods

ensure()

Resolves the specified reference into the actual object and makes sure it is of the specified type.

public static ensure(object|string|array<string|int, mixed>|static $reference[, string|null $type = null ][, ServiceLocator|Container|null $container = null ]) : object

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);
Parameters
$reference : object|string|array<string|int, mixed>|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 = null

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

$container : ServiceLocator|Container|null = null

the container. This will be passed to [[get()]].

Tags
throws
InvalidConfigException

if the reference is invalid

Return values
object —

the object referenced by the Instance, or $reference itself if it is an object.

get()

Returns the actual object referenced by this Instance object.

public get([ServiceLocator|Container|null $container = null ]) : object
Parameters
$container : ServiceLocator|Container|null = null

the container used to locate the referenced object. If null, the method will first try Yii::$app then Yii::$container.

Return values
object —

the actual object referenced by this Instance object.

of()

Creates a new Instance object.

public static of(string $id[, bool $optional = false ]) : Instance
Parameters
$id : string

the component ID

$optional : bool = false

if null should be returned instead of throwing an exception

Return values
Instance —

the new Instance object.

__construct()

Constructor.

protected __construct(string $id[, bool $optional = false ]) : mixed
Parameters
$id : string

the component ID

$optional : bool = false

if null should be returned instead of throwing an exception

Loading…
On this page

Search results