API overview

The API will use the Wordpress plugin API as base. This will give us a solid, known implementation where it is possible to start small and expand. This will save time and mistakes which will allow the focus to be be on the implementation rather then reinventing the API-wheel.

The API needs a core functionality to allow the user of the API to register for filters and actions. The following functions will let the API user add and remove itself from listening to system events.

There is also a need for the developer to know when the plugin has been activated and inactivated. Some plugins need to set up and tear down a database schema and these events and hooks would allow that.

I have not identified any data that would be better off as being filtered rather then action. Perhaps it is just a semtic issue. Could menu restructure perhaps be seen as a filter? Is it an action? Not sure, will keep filters in for now in case they are needed but the main focus will be on actions.

add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1)
apply_filters_ref_array($tag, $value) // This could be renamed to apply_filters since we have no interest in using the apply_filters from wp 
remove_filter( $tag, $function_to_remove, $priority = 10 )  
    
add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1)
do_action_ref_array($tag, $args) // This could be renamed to do_action since we have no interest in using the do_action from wp 
remove_action( $tag, $function_to_remove, $priority = 10 )
        
register_activation_hook($file, $function)
register_deactivation_hook($file, $function) 
register_uninstall_hook($file, $callback)

Filters

/**
 * @global array $wp_filter 
 *               Stores all of the filters added in the form of
 *               wp_filter['tag']['array of priorities']['array of functions serialized']['array of ['array (functions, accepted_args)']']
 *    
 * @global array $merged_filters 
 *               Tracks the tags that need to be merged for later. If the hook is added, it doesn't need to run through that process.
 *
 * @param string $tag 
 *               The name of the filter to hook the $function_to_add to.
 *   
 * @param callback $function_to_add 
 *                 The name of the function to be called when the filter is applied.
 *   
 * @param int $priority optional. 
 *           Used to specify the order in which the functions associated with a particular action are executed (default: 10). 
 *           Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order 
 *           in which they were added to the action.
 *   
 * @param int $accepted_args optional. 
 *            The number of arguments the function accept (default 1).
 *   
 * @return boolean true
 */
function add_filter($tag, $function_to_add, $priority = 10, $accepted_args = 1) 

/**
 * Execute functions hooked on a specific filter hook, specifying arguments in an array.
 *
 * The callback functions attached to filter hook $tag are invoked by calling
 * this function. This function can be used to create a new filter hook by
 * simply calling this function with the name of the new hook specified using
 * the $tag parameter.
 *    
 * @global array $wp_filter 
 *               Stores all of the filters
 *   
 * @global array $merged_filters 
 *               Merges the filter hooks using this function.
 *   
 * @global array $wp_current_filter 
 *               Stores the list of current filters with the current one last
 *
 * @param string $tag 
 *               The name of the filter hook.
 *   
 * @param array $args 
 *              The arguments supplied to the functions hooked to <tt>$tag</tt>
 *   
 * @return mixed 
 *         The filtered value after all hooked functions are applied to it.
 */
function apply_filters_ref_array($tag, $value) // This could be renamed to apply_filters since we have no interest in using the apply_filters from wp 
    
/**
 * Removes a function from a specified filter hook.
 *
 * This function removes a function attached to a specified filter hook. This
 * method can be used to remove default functions attached to a specific filter
 * hook and possibly replace them with a substitute.
 *
 * To remove a hook, the $function_to_remove and $priority arguments must match
 * when the hook was added. This goes for both filters and actions. No warning
 * will be given on removal failure.
 *
 * @param string $tag 
 *                The filter hook to which the function to be removed is hooked.
 *    
 * @param callback $function_to_remove 
 *                  The name of the function which should be removed.
 *
 * @param int $priority optional. 
 *            The priority of the function (default: 10).
 *    
 * @param int $accepted_args optional. 
 *            The number of arguments the function accepts (default: 1).
 * 
 * @return boolean 
 *         Whether the function existed before it was removed.
 */
function remove_filter( $tag, $function_to_remove, $priority = 10 )

Actions

/**
 * Hooks a function on to a specific action.
 *
 * Actions are the hooks that the WordPress core launches at specific points
 * during execution, or when specific events occur. Plugins can specify that
 * one or more of its PHP functions are executed at these points, using the
 * Action API.
 *
 * @uses add_filter() 
 *              Adds an action. Parameter list and functionality are the same.
 *
 * @param string $tag
 *               The name of the action to which the $function_to_add is hooked.
 *
 * @param callback $function_to_add 
 *                  The name of the function you wish to be called.
 *
 * @param int $priority optional. 
 *              Used to specify the order in which the functions associated 
 *              with a particular action are executed (default: 10). Lower 
 *              numbers correspond with earlier execution, and functions with 
 *              the same priority are executed in the order in which they were 
 *              added to the action.
 *
 * @param int $accepted_args optional. 
 *            The number of arguments the function accept (default 1).
 */
function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1)

/**
 * Execute functions hooked on a specific action hook, specifying arguments in an array.
 *
 * Execute functions hooked on a specific action hook.
 *
 * This function invokes all functions attached to action hook $tag. It is
 * possible to create new action hooks by simply calling this function,
 * specifying the name of the new hook using the <tt>$tag</tt> parameter.
 *
 * You can pass extra arguments to the hooks with the <tt>$args</tt> arrray
 *
 * @global array $wp_filter Stores all of the filters
 * @global array $wp_actions Increments the amount of times action was triggered.
 *
 * @param string $tag The name of the action to be executed.
 * @param array $args The arguments supplied to the functions hooked to <tt>$tag</tt>
 * @return null Will return null if $tag does not exist in $wp_filter array
 */
function do_action_ref_array($tag, $args) // This can be renamed to do_action since we have no interest in using the apply_filters from wp 

/**
 * Removes a function from a specified action hook.
 *
 * This function removes a function attached to a specified action hook. This
 * method can be used to remove default functions attached to a specific filter
 * hook and possibly replace them with a substitute.
 *
 * @param string $tag 
 *               The action hook to which the function to be removed is hooked.
 *
 * @param callback $function_to_remove 
 *                 The name of the function which should be removed.
 *
 * @param int $priority optional 
 *            The priority of the function (default: 10).
 *
 * @return boolean 
 *         Whether the function is removed.
 */
function remove_action( $tag, $function_to_remove, $priority = 10 )

General

/**
 * Set the activation hook for a plugin.
 *
 * When a plugin is activated, the action 'activate_PLUGINNAME' hook is
 * called. In the name of this hook, PLUGINNAME is replaced with the name
 * of the plugin, including the optional subdirectory. For example, when the
 * plugin is located in ./plugins/sampleplugin/sample.php, then
 * the name of this hook will become 'activate_sampleplugin/sample.php'.
 *
 * When the plugin consists of only one file and is (as by default) located at
 * ./plugins/sample.php the name of this hook will be
 * 'activate_sample.php'.
 *
 * @param string $file The filename of the plugin including the path.
 * @param callback $function the function hooked to the 'activate_PLUGIN' action.
 */
function register_activation_hook($file, $function)

/**
 * Set the deactivation hook for a plugin.
 *
 * When a plugin is deactivated, the action 'deactivate_PLUGINNAME' hook is
 * called. In the name of this hook, PLUGINNAME is replaced with the name
 * of the plugin, including the optional subdirectory. For example, when the
 * plugin is located in ./plugins/sampleplugin/sample.php, then
 * the name of this hook will become 'deactivate_sampleplugin/sample.php'.
 *
 * When the plugin consists of only one file and is (as by default) located at
 * ./plugins/sample.php the name of this hook will be
 * 'deactivate_sample.php'.
 *
 * @param string $file The filename of the plugin including the path.
 * @param callback $function the function hooked to the 'deactivate_PLUGIN' action.
 */
function register_deactivation_hook($file, $function)

/**
 * Set the uninstallation hook for a plugin.
 *
 * Registers the uninstall hook that will be called when the user clicks on the
 * uninstall link that calls for the plugin to uninstall itself. The link won't
 * be active unless the plugin hooks into the action.
 *
 * The plugin should not run arbitrary code outside of functions, when
 * registering the uninstall hook. In order to run using the hook, the plugin
 * will have to be included, which means that any code laying outside of a
 * function will be run during the uninstall process. The plugin should not
 * hinder the uninstall process.
 *
 * @param string $file
 *
 * @param callback $callback 
 *                 The callback to run when the hook is called. Must be a static method or function.
 */
function register_uninstall_hook($file, $callback)