The oik-shortcodes plugin provides the API reference for each of the plugins and themes documented on this site. This is a brief overview of its implementation.
Custom Post Types
The oik-shortcodes plugin defines the following Custom Post Types ( CPTs ) for documenting APIs and hooks:
- APIs ( oik_api )
- Action and filter hooks ( oik_hook )
- Files ( oik_file )
- Classes ( oik_class )
- Parsed source ( oik_parsed_source )
Some notes about APIs and hooks
Whereas each API may be (uniquely) associated with a plugin, WordPress or PHP, hooks are rather more independent.
- WordPress invokes many hundreds of actions and filters.
- Each plugin or theme can decide which hooks to respond to.
- Plugins and themes also define their own hooks.
According to the WordPress guidelines, each hook should be documented where it is first invoked. The docblock should define the parameters that implementers will need to cater for.
Parsing source files
There are many thousands of APIs defined in hundreds of source files. Documenting the static connections between APIs is fairly easy.
You appear to be a bot. Output may be restricted
function foo() { bar(); }
phpDocumentor(2) does a reasonable job for a static code base.
Discovering and documenting dynamic connections is a little trickier.
You appear to be a bot. Output may be restricted
function bar() { /** * Invoke the 'foobar' action * * Let other plugins know that someone's called foo() which called bar() */ do_action( "foobar" ); }
We have to write code that understands the APIs. Not only do we need to know that do_action() will invoke a hook, we also have to know how a plugin associates its functions to implement the hook. In other words, we need to be able to find calls to add_action( "foobar", "foobar_implementing_function" );
and then associate the “foobar_implementing_function” to the “foobar” hook.
How do we do it?
The oik-shortcodes / oik-batch approach is a client server solution. These notes represent the method used BEFORE support for classes, methods and files were added.
- oik-batch is the client ( createapi2.php plugin )
- oik-shortcodes is the server
- both plugins must have access to the plugin or theme’s source code
- both plugins initially parse the code using token_get_all()
- both plugins must actually load the code to use PHP’s Reflection functions to extract information
- oik-shortcodes uses parts of phpDocumentor to parse docblocks
- oik-batch communicates with the server using wp_remote_post() to
wp-admin/admin-ajax.php - oik-batch loads a subset of WordPress. It does not have any database access.
- Each request from oik-batch is to oiksc_create_api()
- oik-shortcodes is responsible for creating or updating the API, files or class
- oik-shortcodes is responsible for creating and updating hooks and hook associations.
- oik-shortcodes builds the call trees in post meta data
- oik-shortcodes provides shortcodes to display results
This is all nice and easy for statically defined hooks and functions; a lot more complex if they’re dynamically defined.
Pre-requisite plugins
- oik-plugins server – defines the plugins
- oik-themes server – defines the themes
- oik-fields – handles the CPT field entry and display
- oik base plugin
- oik-types is used to extend the definition of posts and pages
- oik-sc-help provides shortcodes used by the oik-shortcode server when documenting shortcodes
Features
- Supports files
- Supports classes and methods.
- Supports dynamic hook names. e.g.
"hook-" . $dynamic - Supports parsing of the WordPress core
- Supports parsing of plugins and themes
Limitations of the current implementation
- The solution does not support classes and methods. This is a planned enhancement.
- The solution does not support dynamic hook names. e.g.
"hook-" . $dynamic - The solution does not support dynamic API names
- The oik-batch plugin is not yet generally available.
Further reading
Other CPTs in oik-shortcodes
The oik-shortcodes plugin was originally developed to document shortcodes and their parameters. SeeShortcodes It has since been extended to include shortcode examples.
- Shortcodes ( oik_shortcodes )
- Shortcode parameters (oik_sc_param)
- Shortcode examples ( shortcode_example )
About the WP-Parser project
The WP-Parser project contains the logic to produce the new API reference for WordPress. It implements a slightly different solution to a similar problem.
