PHP Hooks & Plugins

Notes from an email

I changed how the return values affect plugin execution. Before the
return values were boolean, now they are integer codes.

By default you do not have to return anything.  However if you want to
enforce additional functionality then the return codes are required.


Examples:

When this executes additional plugins will also be called, however, the
default handler, if any, may not be executed.

<?php myPluginFunction() { // does something } ?>


This is the same as above. Default return value.
<?php myPluginFunction() { return DekiPlugin::HANDLED; } ?>


After this plugin is called, no additional plugins for the hook will be
executed.
<?php myPluginFunction() { return DekiPlugin::HANDLED_HALT; } ?>


When unhandled is returned, the point in the code where the hook is
called can see if any plugins actually did anything.  If the unhandled
code is returned then any default actions can check for this code and
perform default actions.
<?php myPluginFunction() { return DekiPlugin::UNHANDLED; } ?>


There is a fourth status code UNREGISTERED which is returned if no
plugins are registered with a hook.
<?php
  $result = DekiPlugin::executeHook(XXX, array());

  if ($result == DekiPlugin::UNHANDLED || $result == DekiPlugin::UNREGISTERED) { // default actions }
?>


With this new return format, we should have more granular control over
how the plugins are executed.