On certain domains in wp-a2z.org I'm seeing "Function does not exist" appearing before the Description and in the middle of the Usage.

e.g. http://buddypress.wp-a2z.org/oik_api/wp_delete_post/

Currently the _oiksc_get_php_files() function will return a list of all the files in a particular directory. This includes .git subdirectory.

The code should ignore any files in the .git directory.

When an inline link is processed in a docblock it should be converted to a link to the given url.
It's not working at present. Don't know why.

There are times when we want to display all the shortcodes for a plugin/theme but the current post is not that particular theme. The particular example is when the theme is a child theme and it's the template theme that is delivering the shortcodes.

We can use this for any child theme of the Genesis theme framework.
This solution will be used in oik-plugins.com and possibly genesis.wp-a2z

Proposed solution

• Add component parameter to the [codes] shortcode.
• The value passed is the post ID of the plugin/theme.
• This is used as the value for the meta key _oik_sc_plugin

When I added logic to cater for @see and @link in oikai_format_markdown_line I took a short cut and implemented the markdown expansion using shortcodes.

I didn't realise that there could be some shortcodes that I didn't want expanding.

When reprocessing the oik API the following Fatal message was issued.

Processing: bw_field_function_title,bw_field_function_title,includes/bw_formatter.inc

Fatal error: Uncaught Error: Call to undefined function gobang() in /home/oikplugi/public_html/wp-content/plugins/oik-bob-bing-wide/shortcodes/oik-plug.php:506
Stack trace:
#0 /home/oikplugi/public_html/wp-content/plugins/oik-bob-bing-wide/shortcodes/oik-plug.php(400): bw_get_readme_data('add-to-any')
#1 /home/oikplugi/public_html/wp-content/plugins/oik-bob-bing-wide/shortcodes/oik-plug.php(350): bw_get_local_plugin_data('add-to-any')
#2 /home/oikplugi/public_html/wp-content/plugins/oik-bob-bing-wide/shortcodes/oik-plug.php(184): bw_get_plugin_info2('add-to-any')
#3 /home/oikplugi/public_html/wp-content/plugins/oik-bob-bing-wide/shortcodes/oik-plug.php(55): bw_get_plugin_info_cache2('add-to-any')
#4 /home/oikplugi/public_html/wp-content/plugins/oik/oik-add-shortcodes.php(205): bw_plug(Array, '', 'bw_plug')
#5 /home/oikplugi/public_html/wp-includes/shortcodes.php(326): bw_shortcode_event(Array, '', 'bw_plug')
#6 [internal function]: do_shortcode_tag(Array)
#7 /home/oikplugi/public_html/wp-includes/shortcodes.php(223): preg in /home/oikplugi/public_html/wp-content/plugins/oik-bob-bing-wide/shortcodes/oik-plug.php on line 506
<table><tbody><tr><th>Plugin name and description</th><th>Plugin links</th><th>Version, total downloads, last update, tested</th></tr>

The shortcode that causes the most hassle is [bw_pages]. This will load content from the website and expand shortcodes within the content. The one that caused the system to crash was [bw_plug]. In oik-plugins.com it crashed because the code couldn't find the readme.txt file for the add-to-any plugin. That's because it's called README.txt in that plugin.

In my local copy I get a different message.... but that's due to another change. The bottom line is still the same. There are shortcodes in the comments that I don't want to be expanded.

Come to think of it, processing the markdown when parsing the code is rather unnecessary.

Similar to issue #9, the performance of oiksc_create_file() is pretty dire in a largish system.
Some files implement many functions.
We need to find links for each of the functions and methods.
If each link takes .5 second to find then it will obviously take a long time to create the oik_parse_source for the file.
It should be able to use a similar caching method to that for APIs.

Currently the createapi2.php file ( in oik-batch ) runs as a client server process.
Processing would be more efficient if run as a batch process, using a local database.

Proposed solution

Use oik-batch's oik-wp.php to invoke WordPress locally against the oik-shortcodes plugin passing the name of the plugin/theme to load, previous version etc.

oik-shortcodes.php will respond to the action hook "run_oik-shortcodes.php"

Each shortcode may support a range of parameters. When a shortcode is registered using the oik options > create shortcode admin page it creates a number of posts with post type oik_sc_param.
At the moment, on oik-plugins, when you view a particular instance of a shortcode parameter you don't see much unless it has been manually edited.

Proposed solution

Automatically display the fields and the syntax for the shortcode.
Two changes are required:

• Automate the creation of additional content for oik_sc_param to append [bw_code name=.] if there aren't already shortcodes in the content
• Change the genesis-oik theme to display a sidebar and include the sidebar-alt widget area - which will display the Information using [bw_fields].

In the WordPress developer reference ( https://developer.wordpress.org ) there are links which allow you to view the source of PHP files on Trac. This then allows you to view version history using the Blame link.

GitHub also provides the ability to view source and Blame.

It would be nice if oik-shortcodes could also provide links, where applicable

View on GitHub depends on the plugin / theme being defined with a GitHub repository
View on Trac will be available for WordPress core, and WordPress plugins & themes.

The PHP parser uses unique token ids for most keywords but there are some reserved words which get treated as T_STRING.

Since oikai_determine_function_type() uses get_defined_functions() to find if a function is a PHP function or not, then the logic to create pragmatic links currently creates links for keywords such as true and false.

This function should be extended to support the reserved words and keywords that are currently being missed.

When run without any parameters and in the correct context the [codes] shortcode displays the shortcodes associated with a plugin. We also want to use it to display the shortcodes associated with a theme.

When a hook is being created by oiksc_create_oik_hook() the post_meta field called '_oik_api_plugin' should be populated with the post_id of the plugin/theme to which the hook is related.

function oiksc_get_plugin() obtains this value from the global $plugin_post.

This field does not appear to be set for themes.

Having added some protection to admin/oik-create-apis.php oiksc_create_shortcode() now dies midway through processing an oik ptions > Create shortcode request.

Perhaps the oiksc_yoastseo() function needs to be extracted from the file. It's needed when creating both the oik_shortcode and the shortcode_params.

The oik_parsed_source post type stores the results of parsing a function, method or file.
The links reflect the primary URL of the site.
These use up more disk space than really necessary, are hardcoded for the http:// protocol.

Suggest that for links to the current site these are relative URLs.

On http://core.wp-a2z.org/oik_hook/ we see a major formatting problem with 3 hooks. Needs to be investigated.

It's worse in http://wp-a2z.org/oik_hook/ and http://develop.wp-a2z.org/oik_hook/

developer.wordpress.org nicely formats @param tags where the parameter type is an array.
Each array field is documented once when the array is first defined
e.g.

* @param array $args {
 *     Optional. An array of arguments.
 *
 *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }

and then it's referenced in all other params via an @see tag.

* @param array $cargs {@see class::method()}
* @param array $fargs {@see function()}

WordPress documentation is here

https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-1-parameters-that-are-arrays

The WordPress documentation refers to phpDocumentor standards which uses a slightly different approach. e.g.

* @param array $args {
*     @var bool   $required Whether this element is required
*     @var string $label    The display name for this element
* }

Great! @var instead of @type

BTW: The WordPress documentation mentions something called hash notation. It doesn't describe what hash notation is supposed to be. But it does link to phpDocumentor PSR-5 recommendations... where there is no mention of the term.

Super..

:sarcasm off.

When viewing a local version at wp.a2z/oik_file/wrapper-php I got the following 3 notices

Notice: Undefined offset: 1 in C:\apache\htdocs\wordpress\wp-content\plugins\oik-shortcodes\classes\class-oiksc-parsed-source.php on line 479

Notice: Undefined offset: 1 in C:\apache\htdocs\wordpress\wp-content\plugins\oik-shortcodes\classes\class-oiksc-parsed-source.php on line 494

Notice: Undefined offset: 1 in C:\apache\htdocs\wordpress\wp-content\plugins\oik-shortcodes\classes\class-oiksc-parsed-source.php on line 492

The problem doesn't occur on the live site http://wp-a2z.org/oik-file/wrapper-php

This Notice was seen on http://woocommerce.wp-a2z.org/oik_api/WC_Shipping_Zone::clear_locations/

Problem description

The oik_shortcodes post type will add a [bw_code] shortcode to the content
if no shortcodes are present. This shortcode is then run and further functionality invoked to display Examples, Snippets etc.

Sometimes this works.
Other times we get recursion, leading to an un-captured Fatal error and an Aw, snap message from Chrome.

Problem explanation

When WordPress SEO is trying to display OpenGraph tags in the header it attempts to obtain the meta description for the post. If this is not available it builds one from the excerpt. If that is not available WordPress creates an excerpt which invokes the_content.

Not knowing any better all the plugins that hook into the_content do their thing and then the excerpt gets produced.

Problems can occur if nested shortcode expansion is performed and 'the_content' filtering goes recursive.

Even if it doesn't go wrong, you'll notice that up to twice as much work is being done than is actually required.

Workaround

Either define a Meta Description in the WordPress SEO meta box.
or deactivate WordPress SEO.

Solution

Add oik_get_the_excerpt() to prevent recursion in 'the_content' processing.
Change the 'the_content' filter logic so that content is only 'enhanced' once.

In http://www.oik-plugins.com/oik_api/_bw_show_contact_form_oik/ the Description contains
Note: The * indicates Required field

Expected output

As shown. The single * should not be converted.

Actual output

Note: The <em>/em> indicates Required field

This leads to the rest of the content being italicised.

Explanation

The asterisk is incorrectly treated as markdown emphasis by the paired_replacements() function.

Proposed solution

Check for overlaps in the paired replacements.

Workaround

Change the Description

In order to be able to use PHP Reflection logic on function prototypes we create dummy functions called oiksc_dummy_function_$fid in temporary files and then load the functions using require_once.

In PHP 7, if the code contains parent:: or self:: then it produces PHP Fatal error: Cannot use "parent" when no class scope is active or Cannot use "self" when no class scope is active

This causes createapi2 to crash. We need a workaround.

In the dynamic reference for an API some of the code inside strings and comments was being processed by the browser, converting HTML entities and tags.
This made some logic difficult to read, especially in parts of the code where translation was being done from the HTML entity to the character or vice-versa.

Proposed solution

• The parsing code should detect situations where HTML entities and tags are used in string constants and comments and adjust them accordingly
• The code should allow for dynamically generated comments for the stripped down file display where function or method links are inserted. These links must continue work

When creating an oik_api, oik_class or oik_file post type object we should also create the
post meta data that's used by Yoast SEO. This will save a bit of time during front-end run-time processing as Yoast SEO will not need to attempt to build the meta description from the post content.

The post meta data to be created includes _yoast_seo_focuskw and _yoast_seo_metadesc.

The same solution could apply when creating an oik_shortcode post type. See also #1

Aside: It would also be nice if we could convince Yoast SEO to stop nagging when the post content is dynamically generated from a single shortcode.

The original logic in oikai_pseudo_reflect() would use Reflection function logic against the actual class, method or function if it was already loaded

We also tested if docblock comments were actually available. WP Engine's code stripped them.

When parsing an updated shared library file this logic led to a Fatal error due to differences between the actual file being parsed and the file that had been loaded. In our case the file we were parsing was libs/bobbfunc.php ( part of oik ) which is shared by oik-bwtrace. The version loaded by oik-bwtrace was older so the start and end line numbers for the functions were different.

Solution

In addition to testing if docblock comments are available, check if shared libraries have been loaded.
If they have then don't trust the code that's already been loaded. It may not match the code we want to parse.

Some shortcodes, such as [hook], [file] and [api] can take time to find the permalink.
There can be many links on a page.
But the user's only going to click on one of them.
So, unless there is some useful information in the link ( such as the API title) there's little point attempting to resolve the link immediately.
404 handling can be used to pragmatically deal with links that weren't found,
or, if it's enabled, we can attempt to use AJAX when the user shows some intent to click on the link.

In the Information block on oik-plugins and WP-a2z we display contextual information for content. Rather than having to manually configure this for the site it would be nice if we could display the version of the currently installed component.
For many custom post types, by following noderef links it is possible to determine the component name. Knowing the post type of the component we can then determine the currently installed version.

For the simplest implementation minor changes will be required to oik-plugins and oik-themes as well.
We'll refer to this issue for that.

On http://wp-a2z.com/oik_api/get_avatar/ attempting to click on links has no effect.
Problem noted using iPad.
Returns section looks iffy. Looks like it can't handle the backticked img tag.
Extract from GitHub source

 * @return false|string `<img>` tag for the user's avatar. False on failure.

the logic in oiksc_display_oik_file() was changed between 1.27.2 and 1.27.6 and now it appears that pagination is no longer being performed. ie. oikai_navi_parsed_source() is not being called. Instead, the inefficient logic is being invoked. This introduces a serious performance issue.

Up to v1.27.2 requests of the form oik-shortcodes/shortcode/funcname were handled via template_redirect hook invokingoiksc_template_redirect`. This was slightly inefficient since the main query was run, then the template redirect kicked in.

In v1.27.3, under "Odds and Sods" the code was changed to implement the request filter.
The solution attempts to caters for DIY oik shortcodes, where the funcname is diy_oik_do_shortcode_simplified by not using this value in the query.

It did not correctly handle other funcname values. It passed a string value for _oik_sc_func, where an integer value ( a noderef ) is expected.

Pragmatic solution

Ignore the value of the funcname. There may be duplicates anyway. e.g. audio is implemented by both WordPress and JetPack.

If the request results in a 404 then perhaps we could either implement the original template redirect logic or, for Genesis based themes, continue to implement oiksc_genesis_404().

The logic in oiksc_build_callees() assumes that it's building the caller/callee associations for a plugin. When invoked for a theme it doesn't find the correct "slug" for the theme, so it fails to determine the component_type and therefore can't find the right file.

Proposed solution

Implement a QAD solution to try getting the post meta value for _oikth_slug when it's failed to get a value for _oikp_slug.

In oiksc_create_oik_hook() a TODO mentions "We need to improve the docblock stuff and record multiple places where a hook is invoked."

The Genesis Theme Framework and its child themes spends a lot of time adding and removing actions and filters. We need to improve the logic for hooks to enable the Dynamic API Reference to be able to show where the hook is referenced.

We also need to improve the logic associated with the docblock... displaying the parameters in the same was as we do for functions and methods.
This needs to take into account the fact that the hook may be invoked from multiple places.

Some plugins remove logic between versions.
Some plugins deprecate functions, others simply remove them.
oik-shortcodes needs to cater for deletions of

• files
• classes
• functions
• methods

and possibly

• hooks
• shortcodes

Example.
The class Jetpack_VideoPress_Shortcode was in jetpack/modules/videopress/shortcode.php in v3.9.6.

The class no longer exists in the latest version ( 4.0.4 ); it was removed by changes in Automattic/jetpack@ba4af49

In a largish site, as the number of records in wp_posts and wp_postmeta increases so the performance of SQL queries degrades. When parsing an API the time taken to find the post IDs of related APIs, classes, hooks etc causes server transactions to take an inordinate amount of time.

On my PC, with 47K posts and 230K post meta each query to find oik_api posts based on post meta data takes up to 500 milliseconds. Note: There are 15K oik_api posts with the same number of post meta rows with meta_key _oik_api_name

This is 3 times the elapsed time when there are a third of the number of records.

Note also that in the larger system the tables are InnoDB, in the other they're MyISAM. This may make a difference; I don't know. I'm using MySQL 5.6.15. InnoDB buffer pool size is 291MiB.

Server transaction times range considerably, but can easily take up to 30 seconds with SQL processing being 80% of the processing.

Proposed solution

We know that performance of queries against wp_postmeta is slow due to the lack of an index on the meta_value column ( one reason why /scribu/wp-posts2posts ), but we aren't yet ready to move away from using wp_postmeta.

We believe some performance gain will be made by pre-loading known information related to the API in question and using in-memory lookups for the relevant IDs and the like.

When attempting to detect the default value of a parameter to a class method we need to be able to cater for parameters declared with default values such as self::MY_CLASS_CONSTANT

The problem occurs in ReflectionParameter->getDefaultValue() in \oik-shortcodes\shortcodes\oik-api-importer.php.

Temporary workaround

Change the code to use the literal value of the constant

http://woocommerce.wp-a2z.org/oik_api/wpdbprepare/

I've recently parsed Yoast SEO (WordPress SEO) on wordpress-seo.wp0a2z.org.
No hooks were listed on the hooks tab. It appears that the _oik_hook_plugin post meta data is not being set.

Could be similar to #13. Note: It worked fine when running locally on Windows.

When a function's docblock contains a list prefixed by *'s then the generated output is displayed incorrectly.

Unexpected result

Instead of appearing as a list the '*' is converted into <em>/em>.

Expected result

We should deal with unnumbered lists which are prefixed by * as list items and not as emphasis

Add support for PHP 7.1.

Below is the first example of a problem with the current code under PHP 7.1

Expected output

When viewing an API such as http://qw/oikcom/oik_api/bw_shortcode_event/ we don't expect to see any Notice about tempnam.

Actual output

Notice: tempnam(): file created in the system's temporary directory in C:\apache\htdocs\wordpress\wp-content\plugins\oik-shortcodes\classes\class-oiksc-function-loader.php on line 116

Notes

I don't remember ever getting a Warning before!
http://php.net/manual/en/function.tempnam.php

Workaround

Create the directory called tmp used by the call $this->tempnam = tempnam( "/tmp", "oikscloa");

Proposed solution

No need to change if it's OK on the Linux servers, but we could change to use wp_tempnam() or call sys_get_temp_dir() in place of "/tmp".

When running the parser locally, parsing a component which is a point release of a Git repository you have to ensure that you don't mix the location from which source code is loaded. If you do, and the code is slightly out of sync, this can lead to a Parse error: syntax error, unexpected end of file in tmpfilename on line n.

This happens because at one point in the processing oiksc_real_file() decides it can load it directly from the Git repo, but a subsequent invocation loads the file contents from the actual component's source file. The problem occurs because the function's start and end lines have been determined from the real file. The error occurs when they differ from the start and end positions in the actual file.

This is a follow on to #17 and is related to #19.

Proposed solution

1. Ensure the installed version matches the Git version
2. Don't load files from the Git repository

Method 1. requires a manual update of the installed code. For some components it's not possible to operate the site with symlinks to the Git repo. It may work if the component is a clone of the Git repo.

Method 2 involves code adjustments.
The simplest approach would to change directory back to the original after determining the changes in the Git repo. A second stage would be to only load the file once.

This issue formalises the need to be able to automatically create and update the shortcodes for a particular component from the latest help and syntax for each shortcode.

We've already developed a routine ( admin/oik-create-codes.php ). It needs to be extended to correctly select the shortcodes to be registered to a particular component.

For those components where oik-sc-help is currently providing the help and syntax, it will use oik-sc-help to perform the mapping of a component's shortcodes: jetpack, edd, woocommerce

The Create API dialog does not support the creation of APIs for themes.
It would be nice to be able to do this when the oik-batch createapi2.php option is not available.

The [hook] shortcode can be used to create a link to a hook - which is either an action hook or a filter.
Some of the output of the oik-bwtrace plugin is written as a combination of HTML and shortcodes.
The hook shortcode needs to be extended to cater for
nested hooks and additional information.
e.g.

[hook after_setup_theme action ],1
[hook after_setup_theme;determine_current_user filter 1],1
[hook after_setup_theme;determine_current_user;sanitize_user filter 3],1

Hopefully no-one uses semi-colons in their hook names!

See bobbingwide/oik-bwtrace#6

When viewing an API in the wp-a2z.org site you sometimes see

Warning: Unterminated comment starting line 99 in /home/bworguk/public_html/wp-content/plugins/oik-shortcodes/shortcodes/oik-api-importer.php on line 2257

It's a known problem - see the notes in oikai_syntax_source - but it's happening a little more often.
WIBNI if we didn't see this message.

The default logic for bw_form_sc_parm_help(), called by bw_form_sc_syntax to display the syntax of a shortcode, is to the result from oik_get_plugins_server().
When oik-shortcodes is active, we'd expect this to to be the current site.
This can be achieved by defining the BW_OIK_PLUGINS_SERVER constant.

Proposed solution

• Define this constant in response to 'init', if not already set.
• Remove the TODO ... where the URL should come from wherever we've defined the oik-shortcode server to be for the selected shortcode! from bw_form_sc_parm_help().

When developing code in a hurry it's quite easy to forget to write all the inline documentation needed for the API reference. Or perhaps there's a small typo in the comment.
This blessed task allows us to make changes without having to resort to raising an issue for every dotted i or crossed t.

But it shouldn't be misused.

See bobbingwide/oik-fields/issues/23

In oik-plugins.com, for the Compatible up to taxonomy, I used to define all the supported versions. Now I just want there to be one term, the highest.

A batch routine ( admin.set_compatible_up_to.php ) is needed to process over 400 posts.

The display of the oik_class post type currently only shows information about the methods that are implemented. It doesn't know about the properties. The oik_file post type strips a class to only show the links to the methods. It doesn't know about properties either.
It would be nice to be able to view the properties of objects.

Components often consist of multiple files in multiple folders. It would be nice to be able to see the structure of the component and traverse the file hierarchy.

This requires

• creation of post_parents
• ability to display the file hierarchy
• simplification of the slug

oik_query_component_by_ID does not properly handle a zero value for post ID, causing it to go recursive and fail by running out of memory.

Example where it fails:

• http://qw/oikcom/oik_shortcodes/bob-3/
• http://oik-plugins.com/oik_shortcodes/bob-3/

Currently parsing of updates requires you to know the version already parsed. Re-parsing after updates have been made to a component should be automatic.

The parse status should show the git commit last parsed.