David Artiss

Plugin README and header information

When developing a plugin, there are two places where ‘meta’ information about the plugin needs to be placed. Each has specific requirements and is used in different places.

The README

The plugin’s README is used by the WordPress.org plugin repository, so all the data contained with this is relevant only to that.

At the top of the standard WordPress README format is a block of fields. If any aren’t relevant to your plugin you should feel free to omit them.

  • Contributors – a list (comma seperated) of the authors of the plugin.
  • Tags –  A comma separated list of relevant tags. Only the first 5 are currently shown but, I believe, up to 12 will be searchable.
  • Donate link – a URL to where the user can donate, if they wish. This could be a specific page on your site containing links, or even directly (tip here) to somewhere, such as PayPal.Me.
  • License –  Details of the license your plugin is using – e.g. “GPLv3”.
  • Licence URI – a link to the relevant licence details.
  • Requires at least – what’s the minimum version of WordPress that this plugin requires?
  • Tested up to – what’s the latest version of WordPress that you’ve tested this plugin with?
  • Requires PHP – what’s the minimum version of PHP that this plugin requires?
  • Stable tag – the current version of your plugin

Here’s an example with all of the above fields in use…
=== Plugin README Parser ===
Contributors: dartiss
Tags: embed, markdown, parser, plugin, readme, view
Donate link: https://www.paypal.me/dartiss
Requires at least: 4.6
Tested up to: 4.8
Stable tag: 1.3.7
Requires PHP: 5.2.4
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

The Header

The header of the main plugin file is used to store meta data used by the WordPress installation itself. When you go into the list of plugins on your site, this is the information displayed alongside each.

The following can be specified…

  • Plugin name – The name of the plugin.
  • Plugin URI – The URL of where the plugin can be found. This can be the WordPress.org repository URL or one on your own site.
  • Description – A description of what the plugin goes.
  • Version – The version of the plugin.
  • Author – The name of the author (a single, full name, not user name or a list).
  • Author URI – A URL for the author, often their home site.
  • Text Domain – The domain name used for internationalization.
  • Domain Path – If you are using your own language files, then this is the path from the plugin folder where the files can be found. Usually specified as /languages/.

License and License URI (see ‘The README’, above) can also be specified but as this information is not displayed, I’ve never seen the relevance of it.

Here’s an example with all of the above fields in use… 

/*
Plugin Name: Plugin README Parser
Plugin URI: https://wordpress.org/plugins/wp-readme-parser/
Description: Display a WordPress plugin's README file in XHTML format, for embedding on a post or page.
Version: 1.3.7
Author: David Artiss
Author URI: https://artiss.blog
Text Domain: wp-readme-parser
Domain Path: /languages/
*/

Now, unlike the README, this information can be extended, if you’d like to display additional metadata next to your plugin. Here, for example, is how to add a ‘Support’ link underneath the main description… 

function set_plugin_meta( $links, $file ) {

	if ( strpos( $file, '[Your plugin filename].php' ) !== false ) { $links = array_merge( $links, array( '<a href="[Your support URL]">' . __( 'Support' ) . '</a>' ) ); }

	return $links;
}

add_filter( 'plugin_row_meta', 'set_plugin_meta', 10, 2 );

You would need to update [Your plugin filename] and [Your support URL] to the relevant values.

The following code will add a link to your Settings page next to the ‘Deactivate’ and ‘Edit’ options under the plugin name… 

function add_settings_link( $links, $file ) {

	if ( strpos( $file, '[Your plugin filename]' ) !== false ) {
		$settings_link = '<a href="[Your settings page URL]">' . __( 'Settings' ) . '</a>';
		array_unshift( $links, $settings_link );
	}

	return $links;
}

add_filter( 'plugin_action_links', 'add_settings_link', 10, 2 );

You would need to update [Your plugin filename] and [Your settings page URL] to the relevant values.