Hooks class

From Apibot
Revision as of 00:37, 9 May 2014 by Grigor Gatchev (talk | contribs) (some start)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

A bot operator typically would not need to check or modify the parameters and/or data flow inside the bot internals. In some rare cases, however, it might be needed. And programmers who would like to modify or extend the bot functionality, typically by writing extensions, might find this ability very useful.

Apibot 0.40.8 introduces a Hooks module, as a part of the Mains module, as the variable $hooks. It allows programmers to attach their own callbacks inside the bot code, and to possibly modify the parameters and data, or the flow itself in-transit. Using these callbacks assumes some knowledge of the internal structure of Apibot.

Creating

Creating an object of the Hooks class requires one parameter - the object settings (part of the bot settings).

Public functions

get ( $modulename, $functionname, $point, $key = NULL )

This function returns the hook or the array of hooks specified:

  • $modulename is the name of the module the hook is in. Typically this will be the object class name for this module. (As Apibot usually doesn't need more than one module of the same type, this defines the module uniquely.)
  • $functionname is the name of the function the hook is in. (Each hook is inside an object function.)
  • $point is the name of the hook point inside the function. (For example, if you try to hook a set_params function in an Action module, you may choose between two hook points. The pre point will have access to the parameters setted before they are passed downwards to the appropriate Module level. The post point will have access to the result of the passing of the parameters after they are passed to the Module level.)
  • $key is the key which which the hook is marked at its point. A point can have many different hooks, each of them having a different key. If this parameter is not specified, or is NULL, an array with all the hooks for this point will be returned.

set ( $modulename, $functionname, $point, $key, $hook )

This function sets a hook at the specified modulename, functionname, point and key. If there is already an existing hook with these parameters, it will be removed from the Hooks module.

The function returns the old hook with these parameters, or NULL if there was none.

del ( $modulename = NULL, $functionname = NULL, $point = NULL, $key = NULL )

This function deletes a hooks at the specified modulename, functionname, point and key.

If $key is not specified or is NULL, all hooks at this point will be deleted. If $point is not specified or is NULL, all hooks for this function will be deleted. If $functionname is not specified or is NULL, all hooks for this module will be deleted. If $modulename is not specified or is NULL, all hooks will be deleted.

The function returns what is deleted - a hook, or an array of all hooks for the point, or an array of all points for the function, or an array of all function for the module, or an array with all modules in the Hooks module. Only things for which there are hooks registered are returned. If nothing is registered for what is specified to be deleted, NULL is returned.

call ( $modulename, $functionname, $point, &$params_array )

This function is used to call the hooks registered for a point. All hooks are called one after another, by the alphabetic order of their keys. It is used inside the Apibot code to call the hooks where appropriate. Programmers might also use it, should they call Apibot hooks from their code.

(By convention hook keys should start with a part that will place them at an appropriate place, and will be separated with an underscore by a part that says something about the nature of the hook - for example, some name for the module that has inserted them.)

The $params_array parameter is an array that contains the parameters that should be passed to the hook. They are passed by the PHP call_user_func_array() function, so that each member of the array comes as a separate parameter for the hook callback. For example, if you have registered a hook with a callback of this profile:

function my_callback ( $context, $API_params )

then you should supply a $params_array that looks like this:

array (
  'context' => $the_object_that_calls_the_hook,
  'API_params' => $the_API_parameters,
)

The keys in this array currently do not play a role - the order of the array member does, it must match the order of the callback parameters. It might be good idea, however, to name the keys in the array appropriately, as later versions of Apibot might start using these keys to supply a functionality.

The profiles the callbacks must have for each hook are listed in the hooks descriptions in the appropriate modules pages.

Hook description

A hook is an array that has the following members:

  • call (mandatory) - the callback itself. It can be any type of callback PHP (and specifically the call_user_func_array() function) supports.
  • require - the pathname of a PHP file that should be require()d just before the callback is called. Programmers can use this to dynamically insert there the code needed, even the code that contains the callback itself.

More types of members can be added in future versions of Apibot.