Download the PHP package aztech/events without Composer

aztech/events

Important notice

This package is the main repository for aztech/events, and does not contain any code. Please refer to the composer.json to view the list of the packages provided by this package.

It imports all extra plugins into your dependencies, and it highly recommended to not depend on this package, as it is present mostly for backwards compatibility.

Stability

Installation

Via Composer

Composer is the only supported way of installing aztech/events . Don't know Composer yet ? Read more about it.

Autoloading

Add the following code to your bootstrap file :

Concepts

aztech/events aims to provide a solid foundation to build event driven architectures in PHP.

The current mainstream approach in existing libraries is currently to produce and consume events within the same process (for example, during a single HTTP request). While this is fine in most cases, it does not fit in well with distributed systems, where events need to cross process/host boundaries. This library attempts to solve that by decoupling totally the publish and the subscribe processes through the use of event channels.

An event channel is simply any resource to which data can be written to and retrieved later (read TCP socket, memory, shared memory, files, message queues...). When an event is published, it is serialized and written to a channel, instead of being dispatched to the event subscribers.

On the other end of the channel, a consumer is responsible for reading incoming events (synchronously or not, depending on the channel type used) and pushing them to a standard event dispatcher. The dispatcher used by the consumer is responsible for dispatching received events to your handlers.

This means you can publish and dispatch events using the following methods :

• Native plugins
  • File
  • Socket
  • Memory
  • Database via PDO (untested)
• Extra plugins
  • AMQP
  • Mixpanel
  • STOMP
  • Redis
  • Wamp
  • ZMQ

If you want to create and publish events, you will need to use a publisher. If you want to consume published events, you will need to use a processor. A processor is responsible for receiving events via whatever transport it uses. The library provides hooks to which you can bind subscribers, which are simple event handlers.

Optionally, the library provides an Application object to which you can easily bind subscribers.

Event matching rules

In events, all events are published and subscribed to on topic basis. An event has to expose a category property, which must return the topic to which the event belongs. It can be any word, or chain of words separated by dots. Each dot indicates a sub-topic.

Subscribers can then choose to subscribe to topic on an exact match basis, or by using wildcards to subscribe to multiple events.

Using wildcards

tl;dr Use '#' to match absolutely anything, '*' to match exactly one unknown word.

Event category matching actually follows the AMQP topic specification, which is quite flexible :

The legacy-amqp-topic-binding filter consists of a described string value. The value value described by the type is interpreted as a pattern to match against the subject field of the Properties section of the message being evaluated.

The pattern is formed using zero or more tokens, with each token delimited by the "." character. The tokens "#" and "*" have special meanings. The token consisting of the single character "*" matches a single word in the subject field. The token consisting of the single character "#" matches zero or more words in the subject field. Thus the filter value "*.stock.#" would match the subjects "usd.stock" and "eur.stock.db" but not "stock.nasdaq".

Basically, a topic name must be composed of letters and/or numbers and dashes. Sub-topics can be specified by using dots :

You can use '*' as a wildcard to match exactly one component in a topic :

There is also '#', which means 0 or more components :

To get check the latest truth table of event matching, please refer to the source of Aztech\Events\Tests\Unit\CategoryMatchTruthTable.

Usage

For simplicity, there are factories available to create publishers and dispatchers.

Listed below are examples for some of the providers. The full documentation is available here.

Basic usage

Checkout the provider specific documentations for more usage examples.