[oik] plugins.com

WordPress plugins and themes

  • Home
  • About
    • lazy shortcodes
    • smart shortcodes
    • oik base plugin
      • oik – donate
      • oik PayPal buttons
      • oik installation
      • oik Button Shortcode button
      • oik changelog
      • oik FAQ
      • oik plugins on SVN
      • oik plugins on GitHub
  • Plugins
    • oik base plugin
    • FREE oik plugins
    • WordPress plugins
    • Premium oik plugins
    • Bespoke oik plugins
  • Shortcodes
    • Shortcode examples
  • Blocks
    • Block examples
  • APIs
    • ALL action and filter hooks
  • Blog
You are here: Home / oik shortcode and API server / Building a plugin’s API reference using oik-shortcodes and oik-batch

Building a plugin’s API reference using oik-shortcodes and oik-batch

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.

See also

  • APIs
  • ALL action and filter hooks
  • Make WordPress Documentation DevHub
  • phpDocumentor
  • [apis]
  • [hooks]
oik shortcode and API server
  • oik_api custom post type
Component:
  • oik block shortcode and API server
Letters: B

Published: April 8, 2014 | Last updated: December 1, 2020

Information

Component:
  • oik block shortcode and API server
Letters: B

Recent plugin updates

oik-css v2.1.0 Update to oik-css v2.1.0 for the ability to style CSS and GeSHi output in documentation. ...
oik-types v2.3.0 Update to oik-types v2.3.0 for improved control over sort order on archives ...
UK-tides v3.1.0 UK-tides v3.1.0 now supports several additional ports. It's built with latest wp-scripts and shared libraries and tested with WordPress 6.1. ...
oik v4.8.2 Upgrade to oik v4.8.2 if you installed oik v4.8.1 from wordpress.org and found that the blocks were missing from the editor. ...
sb-chart-block v1.1.0 sb-chart-block v1.1.0 now uses chart.js v3.9.1. Tested with WordPress 6.0.1 and Gutenberg 13.8.2 ...

Plugins

  • All Plugins
  • oik base plugin
  • FREE oik plugins
  • WordPress plugins
  • Premium oik plugins

Themes

  • FREE themes
  • Bespoke themes
  • Premium themes

Blocks

  • All Blocks
  • Block examples
  • About Blocks

Shortcodes

  • All Shortcodes
  • Shortcode examples
  • About Shortcodes

Reference

  • About APIs
  • All APIs
  • All Classes
  • All Files
  • All Hooks

Support

  • Contact
  • Cookies policy
  • Get API key
  • Privacy
  • Request support
  • Sitemap
  • Stay informed
  • Terms and Conditions
oik-plugins
Email: oikplug@oik-plugins.com

Weight shipping plugins

Find out which cart weight shipping plugin you need for your WooCommerce site.
Which cart weight based plugin do I need?

Site:  www.oik-plugins.com
© Copyright oik-plugins 2011-2023. All rights reserved.


Website designed and developed by Herb Miller of Bobbing Wide
Proudly powered by WordPress and oik-plugins
WordPress 6.1.1. PHP: 7.4.33. Memory limit: 768M