Events

Event System

Introduction

jmsPaymentPlugin uses an event system which is similar to the ECMAScript one. The handling method always receives an instance of jmsPaymentEvent (or a sub class of it) which has the following notable methods:

• preventDefault(): Prevents the default action which would normally be executed next; e.g. if you call this on the pre_transaction event, the transaction will be cancelled, and an exception will be thrown immediately.
• stopPropagation(): Stops the propagation of the event to any remaining listeners.
• getTarget(): Returns the target of the event; usually, this is the payment instance.

If you have registered multiple listeners, the order in which these listeners are executed is not guaranteed. In addition, to the listeners which you can register at run time, you can also add logic which is supposed to be executed on all payments by overwriting the respective methods (preTransactionEvent(), postTransactionEvent(), etc.) in the Payment class. These global listeners are always executed before any listeners registered at run time.

Available Events

For now, the following events are built-in:

• pre_transaction: This is executed before a transaction is performed on a payment. If you call preventDefault() on the event, the transaction will be canceled.
• post_transaction: This is executed after a transaction is performed on a payment.
• post_state_change: This is executed after the payment has changed its state.

You can also dispatch custom events by calling dispatchEvent() on the payment instance.

Registering Listeners

You can register as many listeners on a payment as you like which will be notified when an event is dispatched. Listeners must be instances of Doctrine_Record and implement the jmsPaymentListenerInterface. This interface has exactly one method handlePaymentEvent().

$payment = Payment::create(100.0, 'EUR', new myPaymentData());
$listener = new myPaymentListener();
$listener->save();
$payment->registerListener($listener);