concept-service-locator.md 3.35 KB
Newer Older
Qiang Xue committed
1 2 3
Service Locator
===============

4
A service locator is an object that knows how to provide all sorts of services (or components) that an application
Larry Ullman committed
5
might need. Within a service locator, each component exists as only a single instance, uniquely identified by an ID.
6 7
You use the ID to retrieve a component from the service locator.

Larry Ullman committed
8
In Yii, a service locator is simply an instance of [[yii\di\ServiceLocator]], or from a child class.
9

Larry Ullman committed
10 11 12
The most commonly used service locator in Yii is the *application* object, which can be accessed through
`\Yii::$app`. The services it provides are called *application components*, such as the `request`, `response`, and
`urlManager` components. You may configure these components, or even replace them with your own implementations, easily
13
through functionality provided by the service locator.
14 15 16

Besides the application object, each module object is also a service locator.

Larry Ullman committed
17
To use a service locator, the first step is to register components with it. A component can be registered
18 19 20
via [[yii\di\ServiceLocator::set()]]. The following code shows different ways of registering components:

```php
21 22 23 24
use yii\di\ServiceLocator;
use yii\caching\FileCache;

$locator = new ServiceLocator;
25 26 27 28 29 30 31 32 33 34 35 36

// register "cache" using a class name that can be used to create a component
$locator->set('cache', 'yii\caching\ApcCache');

// register "db" using a configuration array that can be used to create a component
$locator->set('db', [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=localhost;dbname=demo',
    'username' => 'root',
    'password' => '',
]);

37
// register "search" using an anonymous function that builds a component
38 39 40
$locator->set('search', function () {
    return new app\components\SolrService;
});
41 42 43

// register "pageCache" using a component
$locator->set('pageCache', new FileCache);
44 45
```

Larry Ullman committed
46
Once a component has been registered, you can access it using its ID, in one of the two following ways:
Qiang Xue committed
47 48

```php
49
$cache = $locator->get('cache');
Qiang Xue committed
50
// or alternatively
51
$cache = $locator->cache;
Qiang Xue committed
52 53
```

54 55
As shown above, [[yii\di\ServiceLocator]] allows you to access a component like a property using the component ID.
When you access a component for the first time, [[yii\di\ServiceLocator]] will use the component registration
Larry Ullman committed
56
information to create a new instance of the component and return it. Later, if the component is accessed again,
57 58 59 60 61 62
the service locator will return the same instance.

You may use [[yii\di\ServiceLocator::has()]] to check if a component ID has already been registered.
If you call [[yii\di\ServiceLocator::get()]] with an invalid ID, an exception will be thrown.


63
Because service locators are often being created with [configurations](concept-configurations.md),
Larry Ullman committed
64 65
a writable property named [[yii\di\ServiceLocator::setComponents()|components]] is provided. This allows you to configure and register multiple components at once. The following code shows a configuration array
that can be used to configure an application, while also registering the "db", "cache" and "search" components:
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83

```php
return [
    // ...
    'components' => [
        'db' => [
            'class' => 'yii\db\Connection',
            'dsn' => 'mysql:host=localhost;dbname=demo',
            'username' => 'root',
            'password' => '',
        ],
        'cache' => 'yii\caching\ApcCache',
        'search' => function () {
            return new app\components\SolrService;
        },
    ],
];
```