What’s this problem?
WordPress plugins run on a variety of sites running on a variety of server configurations, and a variety of other plugins. It’s common for unexpected configurations to cause trouble for plugin users. Then, users open support threads saying “something went wrong.” The plugin authors then need to ask for configuration information to understand the problem. Is it an incompatibility with some other plugin? Is there something strange about the definition of a database table? Is some operational mode set in an unexpected way? Is the version of some component (php, some php extension, the MariaDB server, some other plugin) older or newer than expected? How can the plugin author find out what might be going wrong?
This happens to me sometimes, especially with plugins like Fast Woo Order Lookup. That plugin happens to add to the functionality of WooCommerce, and needs to work on shops both with and without their high-performance order storage mode activated. The plugin makes an index from order information drawn from a variety of database tables, and sometimes the data in those tables has unexpected character set or collation settings. Some WooCommerce add-on plugins add new types of orders (such as subscriptions) using unexpected metadata fields. The question is, how does a plugin author learn about a user’s configuration?
Asking the user
Asking questions like “what version of WooCommerce do you use?” or “How long ago did you create your shop?” can start to address these questions. (Tables created long ago often have diffferent collations than more recent tables.) But many users have to do some digging in their sites to get the answers. And, if they don’t understand the question their answers can be misleading. So, out of respect for the users — who sell vitamins or clothing or whatever — it’s best to avoid asking gnarly quiz questions to troubleshoot their problems.
debug.log
We can ask users to enable WP_DEBUG and WP_DEBUG_LOG, then send their .../wp-content/debug.log file contents along. Sometimes that is helpful, especially if the problem they have is generating a traceback. This is workable when the plugin is valuable to the user than they know the details of WordPress administration. But production users rightly want to avoid turning on the debugging options.
So what to do? Use Site Health’s Info tab!
WordPress’s Site Health tool page has an Info tab, at Tools -> Site Health -> Info. WordPress core puts lots of useful troubleshooting information into that page. And, plugins (and themes and other add-on modules) can put their own information onto that page. It’s easy to add code to a plugin to do that in a robust way. Simply provide a handler for the 'debug_information' filter. That looks like this:
add_filter( 'debug_information', my_debug_information );
function my_debug_information( $info ) {
$info['my-plugin-name'] = array (
/* My Information */
);
retun $info;
}
That filter is invoked from WP_Debug_Data::debug_data() in core.
How do I format my information?
That $info is an associative array. Its keys are the names of various parts of WordPress. For example, the array element with the key named 'wp-active-theme' describes the currently active theme. Your filter adds one or more entries to that array with keys named for your plugin. As usual, choose your key names to avoid colliding with other parts of WordPress.
Create an array, put your information into, and use it as the value of your new element in the $info arrray. That array looks like this.
array (
'label' => __( 'The caption for my part of the Info tab', 'my-localization-domain' ),
'fields' => array(
'item1-name' => array (
'label' => __( 'The name of my first item', 'my-localization-domain' ),
'value' => $whatever,
),
'item2-name' => array (
'label' => __( 'The name of my second item', 'my-localization-domain' ),
'value' => $whatelse,
),
),
)