README.md 3.34 KB
Newer Older
1
# narrator/narrator-bundle
Daniel Król's avatar
Daniel Król committed
2

Daniel Król's avatar
Daniel Król committed
3 4 5
[![Travis CI](https://travis-ci.org/mleko/narrator-bundle.svg?branch=master)](https://travis-ci.org/mleko/narrator-bundle)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/mleko/narrator-bundle/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/mleko/narrator-bundle/?branch=master)
[![Code Coverage](https://scrutinizer-ci.com/g/mleko/narrator-bundle/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/mleko/narrator-bundle/?branch=master)
Daniel Król's avatar
Daniel Król committed
6

Daniel Król's avatar
Daniel Król committed
7
## Installation
Daniel Król's avatar
Daniel Król committed
8

9
Add project dependency using [Composer](http://getcomposer.org/):
Daniel Król's avatar
Daniel Król committed
10 11

```sh
Daniel Król's avatar
Daniel Król committed
12
$ composer require narrator/narrator-bundle
Daniel Król's avatar
Daniel Król committed
13
```
Daniel Król's avatar
Daniel Król committed
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37

Then register bundle by adding it to `app/AppKernel.php` file

```
<?php
// app/AppKernel.php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...

            new Mleko\Narrator\Bundle\NarratorBundle(),
        );

        // ...
    }

    // ...
}
```

Daniel Król's avatar
Daniel Król committed
38
## Configure listeners
Daniel Król's avatar
Daniel Król committed
39 40 41 42 43 44 45 46 47 48 49

NarratorBundle loads listeners from dependency container.
To use service as a listener you only need to add tag marking service as listener.

If you had service
```
<service class="Foo\BarBundle\UserInvitationSender">
    // .. arguments, configuration
</service>
```

Daniel Król's avatar
Daniel Król committed
50 51 52
```
class UserInvitationSender {
    ...
Daniel Król's avatar
Daniel Król committed
53
    public function handle(\Foo\BarBundle\UserRegistered $event){
Daniel Król's avatar
Daniel Król committed
54 55 56 57 58
        ...
    }
}
```

Daniel Król's avatar
Daniel Król committed
59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
To use it as a listener add tag `narrator.listener`.

```
<service class="Foo\BarBundle\UserInvitationSender">
    // .. arguments, configuration
    <tag name="narrator.listener"/>
</service>
```

Listener don't have to define parameter type in handle method.
```
class UserInvitationSender {
    ...
    public function handle($event){
        ...
    }
}
```
Daniel Król's avatar
Daniel Król committed
77

Daniel Król's avatar
Daniel Król committed
78
Event type can be passed as tag attribute  `event` which should be FQCN of event.
Daniel Król's avatar
Daniel Król committed
79 80 81 82 83 84
```
<service class="Foo\BarBundle\UserInvitationSender">
    // .. arguments, configuration
    <tag name="narrator.listener" event="Foo\BarBundle\UserRegistered"/>
</service>
```
85

Daniel Król's avatar
Daniel Król committed
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
By default event is passed to method `handle` of registered listener. Method name can be changed using `method` parameter.

```
<service class="Foo\BarBundle\UserInvitationSender">
    // .. arguments, configuration
    <tag name="narrator.listener" event="Foo\BarBundle\UserRegistered" method="handleRegistration"/>
</service>
```

Using `method` parameter it is possible to use single service to handle different events.

```
<service class="Foo\BarBundle\NotificationSender">
    // .. arguments, configuration
    <tag name="narrator.listener" event="Foo\BarBundle\UserRegistered" method="handleRegistration"/>
    <tag name="narrator.listener" event="Foo\BarBundle\UserLoggedIn" method="handleLogin"/>
</service>
```

105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
## Configure event buses

This bundle comes pre-configured with event bus called "default" aliased to `narrator.event_bus`.
You might want to use more buses or reconfigure "default" bus. You can do this via configuration
```
narrator:
  event_bus:
    default:
      resolver:
        type: instanceof
    named: ~
```
This configuration defines two buses: "default" and "named". These buses will be registered as `narrator.event_bus.default` and `narrator.event_bus.named`.
`narrator.event_bus.default` will use `InstanceOf` resolver, therefore it will support event inheritance;
`narrator.event_bus.named` will use default configuration based on strict event name comparison.