Hookster is a tool to automatically extract data about the actions and filters of your WordPress theme or plugin. You can use this data in any way you like... For example, you might use the data to create a developer documentation website.
Here's the gist of how this project works — Drop your WordPress theme or plugin files into the src directory, run npm run build in your terminal, and get back the files actions.json and filters.json with data about your hooks.
The motivation here was to generate the data needed to create a developer documentation website for the Jump Start WordPress theme. A reference of all of the available actions and filters has been a popular request from child theme developers for years. However, with a growing library of 500+ hooks, manually creating and maintaining this would be a nightmare.
So this project aims to automate the process of generating this data. Hopefully this tool can be used not only for Jump Start, but for your themes and plugins, as well.
First things first, you must have Node and NPM installed on your computer.
http://blog.teamtreehouse.com/install-node-js-npm-mac
Next, let's talk about how the code in your WordPress theme or plugin needs to be set up to work with Hookster.
Hookster works by going through the DocBlocks found across your theme or plugin's PHP files. The name of your hook is cleverly extracted from the PHP code immediately following each docBlock, and then information about the hook is taken from the docBlock, itself.
So in order for the data to be generated properly, your PHP code needs to follow WordPress's PHP Documentation Standards. For example:
/**
* Summary.
*
* Description.
*
* @since x.x.x
*
* @param string $foo Description.
* @param bool $bar Description.
*/
do_action( 'my_plugin_do_something', $foo, $bar );
/**
* Summary.
*
* Description.
*
* @since x.x.x
*
* @param string $foo Description.
* @param bool $bar Description.
*/
$something = apply_filters( 'my_plugin_modify_something', $foo, $bar );Note: Make sure all of your action and filter names are prefixed with your namespace. In the above examples, the namespace would be my_plugin.
- Clone this repository to your local computer, navigate to the project in your terminal, and run
npm installto install the required Node packages. - Open the project's
package.json, find thenamespaceparameter, and change it to your theme or plugin's namespace. The namespace should be what you prefix all of your action and filter names with. Examples:themename,pluginname,theme_name,plugin_name, etc. Only hook names prefixed with your namespace name will be found. - Drop all of the files of your theme or plugin into the project's
srcdirectory. - Run the command
npm run buildin your terminal. After it's finished, you'll be able to find the filesactions.jsonandfilters.jsonin your project'sdistdirectory.
The data generated within your actions.json and filters.json files will include an object for each hook with the following data.
name: {String} Name of the hook, likemy_plugin_do_something.summary: {String} First paragraph of the docBlock.desc: {String} Remaining paragraphs of the description, after the summary. Paragraphs are separated with\n\n.since: {String} Version number the hook was added to your theme or plugin, pulled from the@sincetag of the docBlock.params: {Array} Parameters passed to the hook.file: {String} File in your plugin or theme, where the hook exists.
Here's an example of what the raw JSON data will look like:
...
{
"name": "themeblvd_icon_browser_value",
"summary": "Filters the value to be inserted for an icon in the icon browser.",
"desc": "By default, this value will be structured with a Font Awesome style class and icon class, like `fas fa-user`.",
"since": "2.7.4",
"params": [
{
"name": "$icon_value",
"type": "string",
"description": "Icon value."
},
{
"name": "$icon",
"type": "string",
"description": "Icon name."
},
{
"name": "$prefix",
"type": "string",
"description": "Style class, like `fas`."
},
{
"name": "$type",
"type": "string",
"description": "Style type, like `solid`."
}
],
"file": "framework/admin/functions/display.php"
},
...The above data was generated from this PHP code:
/**
* Filters the value to be inserted for an icon in the
* icon browser.
*
* By default, this value will be structured with a Font
* Awesome style class and icon class, like `fas fa-user`.
*
* @since 2.7.4
*
* @param string $icon_value Icon value.
* @param string $icon Icon name.
* @param string $prefix Style class, like `fas`.
* @param string $type Style type, like `solid`.
*/
$icon_value = apply_filters( 'themeblvd_icon_browser_value', $icon_value, $icon, $prefix, $type );Jason Bobich