Yii Event
[](https://packagist.org/packages/yiisoft/yii-event)
[](https://packagist.org/packages/yiisoft/yii-event)
[](https://github.com/yiisoft/yii-event/actions/workflows/build.yml)
[](https://codecov.io/gh/yiisoft/yii-event)
[](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/yii-event/master)
[](https://github.com/yiisoft/yii-event/actions?query=workflow%3A%22static+analysis%22)
[](https://shepherd.dev/github/yiisoft/yii-event)
This package is a configuration wrapper for the [yiisoft/event-dispatcher](https://github.com/yiisoft/event-dispatcher) package.
It is intended to make event listener declaration simpler than you could ever imagine.
All you need is to use any [PSR-11](https://www.php-fig.org/psr/psr-11/) compatible DI container.
## Requirements
- PHP 8.1 - 8.5.
## Installation
The package could be installed with [Composer](https://getcomposer.org):
```shell
composer require yiisoft/yii-event
```
## General usage
### DI configuration
You can find default configuration in the [config directory](config):
- [di.php](config/di.php) contains the configuration for the [PSR-14](https://www.php-fig.org/psr/psr-14/) interfaces.
- [di-web.php](config/di-web.php) and [di-console.php](config/di-consle.php) contains the configuration for the `Yiisoft\EventDispatcher\Provider\ListenerCollection`.
- [params-web.php](config/params-web.php) and [params-console.php](config/params-consle.php) contains parameters for `web` and `console` configurations.
All these settings will be used automatically in projects with the [yiisoft/config](https://github.com/yiisoft/config).
If you have custom `events` configuration group name, for example `events-api`, redefine it in the `eventsConfigGroup` params key.
params.php
```php
return [
'yiisoft/yii-event' => [
'eventsConfigGroup' => 'events-api',
],
]
```
### Event configuration example
The configuration is an array where keys are event names and values are array of handlers:
```php
return [
EventName::class => [
// Just a regular closure, it will be called from the Dispatcher "as is".
static fn (EventName $event) => someStuff($event),
// A regular closure with additional dependency. All the parameters after the first one (the event itself)
// will be resolved from your DI container within `yiisoft/injector`.
static fn (EventName $event, DependencyClass $dependency) => someStuff($event),
// An example with a regular callable. If the `staticMethodName` method contains some dependencies,
// they will be resolved the same way as in the previous example.
[SomeClass::class, 'staticMethodName'],
// Non-static methods are allowed too. In this case `SomeClass` will be instantiated by your DI container.
[SomeClass::class, 'methodName'],
// An object of a class with the `__invoke` method implemented
new InvokableClass(),
// In this case the `InvokableClass` with the `__invoke` method will be instantiated by your DI container
InvokableClass::class,
// Any definition of an invokable class may be here while your `$container->has('the definition)`
'di-alias'
],
];
```
The dependency resolving is done in a lazy way: dependencies will not be resolved before the corresponding event
will happen.
### Configuration checker
To help you with event listener configuration validation there is the `ListenerConfigurationChecker`. It is converting
your whole listener config to actual callables at once to validate it. It is intended to be used in development environment
or in tests since it is a resource greedy operation in large projects. An `InvalidEventConfigurationFormatException`
will be thrown if your configuration contains an invalid listener.
Usage example:
```php
$checker->check($configuration->get('events-web'));
```
## Documentation
- [Internals](docs/internals.md)
If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
## License
The Yii Event is free software. It is released under the terms of the BSD License.
Please see [`LICENSE`](./LICENSE.md) for more information.
Maintained by [Yii Software](https://www.yiiframework.com/).
## Support the project
[](https://opencollective.com/yiisoft)
## Follow updates
[](https://www.yiiframework.com/)
[](https://twitter.com/yiiframework)
[](https://t.me/yii3en)
[](https://www.facebook.com/groups/yiitalk)
[](https://yiiframework.com/go/slack)