Introduction

The PtcEvent component provides an observer implementation for your application, allowing the programmer to add and listen for events. Event execution order can be controlled with a priority parameter. The class can add closures and class methods as event listeners. Wildcards are also accepted to watch event listeners execution. There are also helper functions available for this class, shipped with the ptc-helpers.php file. The class also supports event removal if needed. Event Propagation can also be prevented.

Main Features:

Accepts closures and class methods as event listener
Supports wildcards for all added events
Helper functions can be added with the ptc-helpers.php file
Supports event execution order with the priority parameter
Supports Event removal if needed
Can Retrieve a list of added events
Supports event propagation prevention

Getting Started

To start using the event dispatcher, simply include the class file, and start adding event listeners. Here's a quick and simple example:

require_once( 'PtcEvent.php' );
// add an event listener with a closure as callback
PtcEvent::listen( 'form.submit' , function( $data )
{
  // do some stuff
  print "called event with closure as callback!<br><br>";
} );

Adding Event Listeners

To add event listeners, the method PtcEvent::listen( ) can be used. The following paragraphs will demostrate how event listeners can be added to your application.

Adding Closures as Listeners

The fastest way to add an event listener is using closures, have a look at the following example:

PtcEvent::listen( 'form.submit' , function( $data )
{
  // do some stuff
  print "called event with closure as callback!<br><br>";
} );

Adding Declared Functions As Listeners

Declared functions can also be added as listeners:

  // adding a function as callback
function event_callback( $data )
{
  // do some stuff
  print "event_callback( ) function called!<br><br>";
}
PtcEvent::listen( 'form.error' , 'event_callback' ); 

Adding Classes As Listeners

Classes can also be added as event listeners, as shown in the next example:

// registering classes as listeners
class MyObserver 
{
  public function handle( $data )
  {
      // default method that will be called
      // do some stuff
      print "default handle( ) method called<br><br>";
  }
}
// registering the class as event listener
PtcEvent::listen( 'form.success' , 'MyObserver' );

By default, the PtcMapper tries to call the method handle( ) from a class, to add a custom method use the "@" operator:

class MyObserver 
{ 
  public function myMethod( $data )
  {
      // do some stuff
      print "custom method has been called<br><br>";
  }   
}
// registering the class with a custom method
PtcEvent::listen( 'form.error' , 'MyObserver@myMethod' );

Using Wildcards

Wildcards "*" are also accepted for the "$event" argument:

// using wildcards , event name is passed as argument
PtcEvent::listen( 'form.*' , function( $data , $event )
{
  // do some stuff
  print "wildcard called on event " . $event . ':<pre>';
  print print_r( $data , true ) . "</pre><br><br>";
} );

This listener will be called every time an event with the prefix "form" is called.

Assigning Priority

The argument "$priority" can be used to control the events execution order:

// higher priority numbers will execute first

PtcEvent::listen( 'form.error' , 'event_callback' , 10 );

Firing Events

To fire events, the method PtcEvent::fire( ) can be used:

// firing an event

PtcEvent::fire( 'form.submit' , array( 'form data' ) );

To be able to manipulate data with the event listeners, the "&" can be used to reference the "$data" argument:

$data = 'some data';
// adding "&" to reference and manipulate the data with the listeners
PtcEvent::fire( 'ptc.query' , array( &$data ) ); 

Preventing Event Propagation

To prevent propagation, you can retun "false" inside an event listener, and all events following that event will not be fired:

// return false to prevent event propagation
PtcEvent::listen( 'form.error' , function( $data )
{
  // do some stuff
  print "event propagation has been stopped!<br><br>";
  return false; // preventing event propagation
} );

Note: Use "$priority" argument to control execution order, refer to Assigning Priority to know more over this topic.Preventing Events Propagation

Retrieving Previously Added Events

To retrieve previously added events, use the method PtcEvent:getEvents( );

// getting the current event listeners

print_r( PtcEvent::getEvents( 'form.error' ) );

Note: If the argument "$name" is not used, all currently added events will be returned.

Removing Event Listeners

To remove event listeners the method PtcEvent::remove( ) can be used:

// removing the last added event
PtcEvent::remove( 'form.error' );
// removing the first event by key
PtcEvent::remove( 'form.error' , 0 ); 

Using The Library Helpers

The PhpToolCase library, provides helper functions for the PtcEvent component. To be able to use the class with the ptc-helpers.php functions, the component needs to be registered. Use the method PtcEvent::register( ) before calling any of the helper functions related with the PtcEvent component

Note: The PtcHandyMan component automatically registers the PtcEvent class when the method PtcHandyMan::register( ) is called.

Table of Contents