Simulating Events with PHP 5

PHP has the drawback of not supporting events. Fortunately, a basic structure can be built to support events in PHP 5. This article tackles that problem with some proof of concept code.

One of the big drawbacks of PHP has always been its lack of events. Events allow programmers to attach new behaviors to objects that are activated when certain conditions are met. Those conditions are announced to the outside world as an event. While all object languages that support events do so a bit differently, some being very simple like JavaScript or VB.NET, others being a real pain in the rear like C#, it should go without saying that the task of creating a framework to simulate events will be much harder.

It seemed reasonable to me that some sort of basic structure could be established to support events in PHP 5, so I set out to whip something up as quickly as possible as a proof of concept. The contents of this article are the work of roughly one programming hour and surely stand to be improved upon, but the basic idea is this: instantiate an object and attach event handlers; the handlers will be executed when the events they are associated with are raised.

This is not an article for beginners, but I would not say you have to be a guru to understand the concepts and the code here. I have tried to keep it as minimal as possible to stay on point.

The Event and EventCollection Classes

First we need to create a simple object to store whatever event information we may need and an object to contain a collection of events. The reason we do not simply store them in an ArrayObject is because we need to be able to quickly check to see whether an event exists in a given collection, which requires code written specifically for the task.

Here is the Event class:

class Event
{
     private $name;    

     public function GetName()
     {
          return $this->name;
     }    

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

As you can see, the class is essentially a container for a string. You could do away with this class in the examples given here, but I chose to go ahead and use an Event class in case at some point we need to store more information about a particular event. The EventCollection class basically wraps an ArrayObject and provides a function to check for an event by name.

class EventCollection
{
     private $events;

     public function __construct()
     {
          $this->events = new ArrayObject();
     }

     public function Add($event)
     {
          if (!$this->Contains($event))
              $this->events->Append($event);
     }    

     public function Contains($event)
     {
          foreach ($this->events as $e)
          {
              if ($e->GetName() == $event)
                   return true;
          }
     }
}

Again, I chose to use classes for events rather than simply an ArrayObject of strings to provide support for future additions. There is no code in either of these classes that requires explanation, so let us continue.

{mospagebreak title=The EventHandler and EventHandlerCollection Classes}

To create an event handler, we need to know the event to which it was attached and we need to know what to do when the handler finds out about the event being raised. Since we cannot create function references, and lack of native support for events eliminates the usefulness of anonymous functions, we will use an approach similar to C# delegates, but with less fuss. We will create an EventHandler object by passing it an Event object and the name of the callback function, which will later be called in an eval() statement (ugly, but it will do).

class EventHandler
{
     private $event;
     private $callback;    

     public function GetEventName()
     {
          return $this->event->GetName();
     }    

     public function __construct($event, $callback)
     {
          $this->event = $event;
          $this->callback = $this->PrepareCallback($callback);
     }    

     public function Raise($sender, $args)
     {
          if ($this->callback)
              eval($this->callback);
     }    

     private function PrepareCallback($callback)
     {
          if ($pos = strpos($callback, ‘(‘))
              $callback = substr($callback, 0, $pos);    

          $callback .= ‘($sender, $args);';         

          return $callback;
     }
}

This class actually has some substance to it. The Raise() method actually runs the callback, and the PrepareCallback() method makes sure the callback has the proper signature for a delegate, that is, (Object $sender, EventArgs $e), for those of you who are familiar with C#. Since I didn’t care to make an EventArgs class, $args will just be an array. This provides the handler functions with context that they would otherwise lack. They know the calling object, $sender, and they can be given parameters with $args.

The EventHandlerCollection also provides a test for membership with the Contains() method, basically what we saw with the EventCollection, and it provides a RaiseEvent() method that picks through its list of handlers and calls Raise() on the right one. This keeps event triggering simple later on when we look at the event enabled class. Here is the EventHandlerCollection class:

class EventHandlerCollection
{
     private $handlers;    

     public function __construct()
     {
          $this->handlers = new ArrayObject();
     }    

     public function Add($handler)
     {
          $this->handlers->Append($handler);
     }    

     public function RaiseEvent($event, $sender, $args)
     {
          foreach ($this->handlers as $handler)
          {
              if ($handler->GetEventName() == $event)
                   $handler->Raise($sender, $args);
          }
     }
}

We now have our four “framework” classes. It is time to move on to a class that can actually register event handlers and raise events.

{mospagebreak title=The Event-Enabled Class}

To enable a class with events, there are a few prerequisites, given our existing classes. First, it needs to contain a list of available events. Second, it needs to be able to trigger, or raise, its events through some helper method. Third, it needs to be able to register event handlers. Note that any given event can have more than one event handler.

The code for this class, which we are calling MyEventClass, is actually pretty simple. In the code below, you will notice that the class is wired up for two events, OnLoad and OnUnload. You will also notice that we pass an EventHandlerCollection into the constructor. To support the OnLoad event, which fires at the end of the constructor, we would have to already have a handler in place to make use of it – which means, in general, classes implementing this pattern will need to provide a $handlers parameter in the constructor.

class MyEventClass
{
     private $events;
     private $eventHandlers;    

     public function __construct(EventHandlerCollection $handlers
= null)
     {
          $this->events = new EventCollection();         

          if ($handlers)
              $this->eventHandlers = $handlers;
          else
              $this->eventHandlers = new EventHandlerCollection
();          

          $this->InitEvents();
          $this->TriggerEvent(‘OnLoad’, array(‘arg1’=>1));
     }    

     public function __destruct()
     {
          $this->TriggerEvent(‘OnUnload’, array(‘arg2’=>2));
     }    

     public function RegisterEventHandler($handler)
     {
          if ($this->events->Contains($handler->GetEventName()))
              $this->eventHandlers->Add($handler);
     }
     private function InitEvents()
     {
          $this->events->Add(new Event(‘OnLoad’));
          $this->events->Add(new Event(‘OnUnload’)); 
     }
     private function TriggerEvent($eventName, $args)
     {
          $this->eventHandlers->RaiseEvent($eventName, $this,
$args);
     }
}

To quickly review the class methods, from the bottom up, there is TriggerEvent(), which accepts an event name and any relevant arguments. It directly calls EventHandlerCollection::RaiseEvent, which passes the event along to the appropriate handler or handlers, if one does in fact exist. Since the RaiseEvent() method of EventHandlerCollection does not have an exit condition when it finds a handler matching the raised event, we can have as many handlers for an event as we want.

InitEvents() is a crude way to register available events with the class. We have to populate the EventCollection somehow, and this seemed to me the best way to do it. RegisterEventHandler() is simply a wrapper for EventHandlerCollection::Add(), allowing us to attach handlers to an object after it has been instantiated. I would suggest passing all handlers in the constructor for clarity’s sake, but the RegisterEventHandler() method is available nonetheless.

Notice in __construct() and __destruct(), TriggerEvent() is called. The result of calling TriggerEvent(), through a few levels of indirection, calls the code you passed in when you created your EventHandlers. That brings me to the final bit of code for this article – using MyEventClass.

{mospagebreak title=Using the Event-Enabled Class}

Using MyEventClass is fairly straightforward. You create an EventHandlerCollection and any event handling methods you want, and you instantiate the class.

$handlers = new EventHandlerCollection();
$handlers->Add(new EventHandler(new Event(‘OnLoad’),
‘handleLoad’));
$handlers->Add(new EventHandler(new Event(‘OnUnload’),
‘handleUnload’));

$obj = new MyEventClass($handlers);
$obj = null;

function handleLoad($sender, $args)
{
     print ‘object ‘.get_class($sender).’ loaded with ‘.count
($args).’ args!<br />';
}

function handleUnload($sender, $args)
{
     print ‘object ‘.get_class($sender).’ unloaded with ‘.count
($args).’ args!';
}

If you create a PHP page with all the code in it from this article and run it, you will see the following on your screen:

object MyEventClass loaded with 1 args!
object MyEventClass unloaded with 1 args!

Obviously this is a rather minimalistic (and pointless) implementation, but it does demonstrate the usage of the event handlers and the event-enabled class. Pretty cool, yes?

Conclusion

Hopefully this article has piqued your interest and you will experiment, improve my code, and create a fantastic open source event framework for PHP, which I am far, far too lazy to do myself. There are some obvious points where refactoring is called for, such as creating an interface or an abstract base class that event-enabled classes adhere to, or providing a more effective design of the event and handler classes. I intend to use the code I’ve created here in my next PHP project, and I hope you will, too. Be sure to let me know how it works out and post any nifty improvements in the dicussion thread of the article.

[gp-comments width="770" linklove="off" ]

chat