yiisoft/yii-event

Yii Event

2.1.0 2023-11-04 15:57 UTC

This package is auto-updated.

Last update: 2024-03-07 10:51:20 UTC


README

68747470733a2f2f796969736f66742e6769746875622e696f2f646f63732f696d616765732f7969695f6c6f676f2e737667

Yii Event


Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage Mutation testing badge static analysis type-coverage

This package is a configuration wrapper for the 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 compatible DI container.

Requirements

  • PHP 8.0 or higher.

Installation

The package could be installed with composer:

composer require yiisoft/yii-event

General usage

DI configuration

You can find default configuration in the config directory:

All these settings will be used automatically in projects with the yiisoft/config.

If you have custom events configuration group name, for example events-api, redefine it in the eventsConfigGroup params key.

params.php

<?php

declare(strict_types=1);

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:

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:

$checker->check($configuration->get('events-web'));

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

License

The Yii Event is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack