venomous0x/WhatsAPI — pull request #557 by zephyern (2013-12-21 22:57:48+00:00)
Title: Explicitly Define WhatsAppEvents & Add Beginning of Testing Framework

As proposed in issue https://github.com/venomous0x/WhatsAPI/issues/554, here is a way we can define and document all events in an interface(see: WhatsAppEventListener.php). I added example code in EVENTS.md, but basically the difference is:

To add an event listener, you'd do this: (Where MyEventListener extends WhatsAppEventListenerBase)
$w->eventManager()->addEventListener(new MyEventListener());

Instead of this: (Although this way is still supported.)
$w->eventManager()->bind('onConnect', 'MyFunction_onConnect');

And now MyEventListener will be able to handle any event that WhatProt can raise.

Pros:
* Interface to enforce that documentation and code (including method names are arguments) are keep in sync. The documentation will now be a part of the interface.
* Raising an event in whatsprot.class.php will call a specific method in WhatsAppEvent which will also help to enforce that the arguments sent and in sync with the interface.
* Added the beginnings of a unit test framework. We should now run WhatsAppEventTest.php before committing any new code. It will simulate some WhatsApp messages and ensure that the events are raised as expected. (This is a work in progress.)
* All this code should be backwards compatible.

Cons:
* I added quite a lot of code here and it does make the code more complex.
* Adding new events/arguments will require more code changes.
* I didn't do any performance testing, but due to the change in event processing this new way will likely be a little slower since there's a little more work to be done each time an event is fired.

Questions:
* What are the actual arguments to onGetPrivacyBlockedList?
* What is our target version of PHP that we'd like to support? (I'm using 5.4 but not sure if I should be testing on an earlier version.)
* How backwards compatible do we want to be? I'd like to remove some of the "Legacy" event firing / handling, but I'm sure that would break existing users.
* Why is $event_listeners static in WhatsAppEvent? Any concern if I make it non-static?

Thanks for reviewing. Looking forward to any feedback.