# Event dispatcher

[![Build Status](https://secure.travis-ci.org/onoi/event-dispatcher.svg?branch=master)](http://travis-ci.org/onoi/event-dispatcher)
[![Code Coverage](https://scrutinizer-ci.com/g/onoi/event-dispatcher/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/onoi/event-dispatcher/?branch=master)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/onoi/event-dispatcher/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/onoi/event-dispatcher/?branch=master)
[![Latest Stable Version](https://poser.pugx.org/onoi/event-dispatcher/version.png)](https://packagist.org/packages/onoi/event-dispatcher)
[![Packagist download count](https://poser.pugx.org/onoi/event-dispatcher/d/total.png)](https://packagist.org/packages/onoi/event-dispatcher)

A minimalistic event dispatcher (observer) interface that was part of the [Semantic MediaWiki][smw] code base and
is now being deployed as independent library.

## Requirements

PHP 5.3/HHVM 3.3 or later

## Installation

The recommended installation method for this library is by either adding
the dependency to your [composer.json][composer].

```json
{
	"require": {
		"onoi/event-dispatcher": "~1.0"
	}
}
```

## Usage

```php
class BarListener implements EventListener {

	public function execute( DispatchContext $dispatchContext = null ) {
		// Do something
	}

	public function isPropagationStopped() {
		return false;
	}
}
```
```php
class ListenerCollectionRegistry implements EventListenerCollection {

	private $eventListenerCollection;

	public function __construct( EventListenerCollection $eventListenerCollection ) {
		$this->eventListenerCollection = $eventListenerCollection;
	}

	public function getCollection() {
		return $this->addToListenerCollection()->getCollection();
	}

	private function addToListenerCollection() {

		$this->eventListenerCollection->registerCallback( 'do.something', function() {
			// Do something
		} );

		$this->eventListenerCollection->registerListener( 'notify.bar', new BarListener() );

		return $this->eventListenerCollection;
	}
}
```
```php
$eventDispatcherFactory = new EventDispatcherFactory();

$listenerCollectionRegistry = new ListenerCollectionRegistry(
	$eventDispatcherFactory->newGenericEventListenerCollection()
);

$eventDispatcher = $eventDispatcherFactory->newGenericEventDispatcher();
$eventDispatcher->addListenerCollection( $listenerCollectionRegistry );

class Foo {

	use EventDispatcherAwareTrait;

	public function doSomething() {

		// No context
		$this->eventDispatcher->dispatch( 'do.something' );

		$dispatchContext = new DispatchContext();
		$dispatchContext->set( 'dosomethingelse', new \stdClass );

		// Using `DispatchContext`
		$this->eventDispatcher->dispatch( 'notify.bar', $dispatchContext );

		// Using an array as context which is later converted into
		// a `DispatchContext`
		$this->eventDispatcher->dispatch( 'notify.foo', [ 'Bar' => 123 ] );
	}
}

$instance = new Foo();
$instance->setEventDispatcher( $eventDispatcher );
$instance->doSomething();
```

## Contribution and support

If you want to contribute work to the project please subscribe to the
developers mailing list and have a look at the [contribution guidelinee](/CONTRIBUTING.md). A list of people who have made contributions in the past can be found [here][contributors].

* [File an issue](https://github.com/onoi/event-dispatcher/issues)
* [Submit a pull request](https://github.com/onoi/event-dispatcher/pulls)

### Tests

The library provides unit tests that covers the core-functionality normally run by the [continues integration platform][travis]. Tests can also be executed manually using the PHPUnit configuration file found in the root directory.

### Release notes

- 1.1.0 (2019-01-27)
  - Allowed `EventDispatcher::dispatch` to take an array as context object
  - Added the `EventNotDispatchableException` and `Subscriber` interface
  - Added the `EventDispatcherAwareTrait` class

* 1.0.0 initial release (2015-03-25)

## License

[GNU General Public License 2.0 or later][license].

[composer]: https://getcomposer.org/
[contributors]: https://github.com/onoi/event-dispatcher/graphs/contributors
[license]: https://www.gnu.org/copyleft/gpl.html
[travis]: https://travis-ci.org/onoi/event-dispatcher
[smw]: https://github.com/SemanticMediaWiki/SemanticMediaWiki/