Developers/Order plugins/Implementation/Methods

Method register
The register method is responsible to register the plugin provider itself on the basket. It uses the addListener method of the basket implementing MW_Observer_Publisher_Interface to subscribe itself for the named events. Events in the basket class are published with MW_Observer_Publisher_Abstract::_notifyListeners, so look out for occurrences of this method. Each notifying method publishes an &lt;event&gt;.before and an &lt;event&gt;.after before and after executing its code respectively. This gives you full control when to trigger your plugin. Most of the methods publishing events are self explaining:


 * setCustomerid: setUserId.before, setUserId.after
 * setLocale</tt>: setLocale.before, setLocale.after
 * addProduct</tt>: addProduct.before, addProduct.after
 * deleteProduct</tt>: deleteProduct.before, deleteProduct.after
 * setAddress</tt>: setAddress.before, setAddress.after
 * deleteAddress</tt>: deleteAddress.before, deleteAddress.after
 * setService</tt>: setService.before, setService.after
 * addCoupon</tt>: addCoupon.before, addCoupon.after
 * deleteCoupon</tt>: deleteCoupon.before, deleteCoupon.after
 * check</tt>: check.before, check.after (events before and after the checks if the customer can start the checkout process)
 * finish</tt>: setOrder.before (event after the customer has finished the checkout process but before the order is written to the database)

Method update</tt>
The update</tt> method is executed by the basket for the events the plugin provider has been registered for, so you have to put the code of the actual manipulation the plugin should perform in this method. There are some things you should take care of:


 * Use logging at debug level : To log the activity of your plugin, at least that it's update method was called on event. It totally pays off when you have to debug your code and can retrace the actions of your plugins in the administration interface log entries. Event-driven code sometimes tends to have surprising effects.


 * Check the passed order object : It must implement MShop_Order_Item_Base_Interface</tt>, otherwise throw an exception. This guards you against bugs in other extensions. The problem is, that it's not possible in PHP to implement the method with a more specific parameter signature demanding a subtype like MShop_Order_Item_Base_Interface</tt>. To avoid that all objects of the very generic type are accepted by update</tt> you have to write this little test.


 * Use the plugin configuration : It can store the configuration parameters make the tests of your plugin provider suitable for more cases. The configuration consists of key/value pairs stored in an array. If a configuration value is needed by the plugin, you should test for it and handle a missing value by either skipping the test or using a reasonable default value. The configuration options can be set in the administration interface. Please note, that the administration interface is currently not capable of creating a multidimensional arrays as configuration.


 * Use exceptions : When something goes wrong, throw an exception of type MShop_Plugin_Provider_Exception</tt>. This class has a special fourth parameter where specific information about the occurred problem can be passed. In the checkout process, the error domain, type and code are used to create appropriate error strings. For problems related to products in the basket the error domain and the position of the product in the basket are used to highlight the problematic product in the basket.


 * Return a boolean value : The method should return true if everything worked fine. If false is returned, the execution of all following plugins for this event are skipped. The advantage is that the code execution is not aborted completely by throwing an exception. To gain control over the order plugins are executed in, you can use the "positon" property available in each plugin record. The plugin item with the lowest number is executed first. If two or more plugins share the same number, the order of these plugins is arbitrary.

<< Previous: Example plugin provider | Next: Plugin provider decorators >>