PHP Events

Midgard 1.9 introduce events handling. A feature completely unknown in previous Midgard releases, and also unknown in PHP itself.

Every Midgard object can connect to particular event(signal) with particular user's defined callback. An object may connect to multiple events with multiple callbacks. Also there might one default created callback for every registered class.

A callback might be a function or object's method. There's no limitation on how many arguments callback function may require. The only one ( very important ) rule for callback functions is that the first expected argument must be an object which is connected to event's callback.

Example of function registered as callback:

<?php

function my_callback($object, $user_data)
{
    echo "Event for object identified with guid '{$object->guid}' ";
}
?>

Midgard php extension always sets object as first function parameter. It's not possible to overwrite it. Your data starts at second parameter.

You can connect your callback function to instance in two ways:

Create callback and connect to instance

Object is created and callback is connected to event using connect method. When particular event is emited, your callback is invoked only for this instance which connected callback and event.

Create callback and connect to class

Special case when callback is registered as default one for particular event. Callback is still invoked only for instance which emits event, but you do not have to connect callback to every single created instance. Read about midgard_object_class::connect_default.

Event(signal) emission in Midgard core is not aware of what callback really does. So for example you can not abort underlying function or method execution. Instead , you should throw exception, handle error your specific way or just abort application

Additionally you may emit registered signal using emit method. It's not recommended to emit signals registered in core as it may duplicate callback invocations. However application may emit signal due to language bindings implementation. For example you may emit signal like action_loaded because it's not possible to connect callback to such event on PHP level.

References: