Plugin JSON File

The plugin.json file is an optional JSON file in the root directory of the plugin that contains the plugin's metadata. If omitted, the plugin's metadata will be parsed from the plugin's header in the main file.

This file is mostly used by the built-in PluginModule. Refer to the Plugin Module documentation to see how it is used.

Purpose

Plugin metadata is often read from the plugin's main file, using the WordPress get_plugin_data() function. This function needs to read the first 8Kb from the plugin PHP file, and then parses it using regex and string manipulation functions, all while triggering WordPress hooks, translation functions, sanitization functions, and more. This is very slow, and doesn't even return the entire data in some cases (such as multi-line descriptions).

By contrast, a JSON file can be parsed very efficiently using PHP's json extension, making it much faster. Using such a file also means that we don't inherit the same limitations as the get_plugin_data() function, such as the 8Kb limit and the inability to parse multi-line descriptions.

Structure

The structure of the JSON file is as follows:

• slug - (*) A kebab-case slug, usually equivalent to the plugin's directory name and WordPress.org permalink.
• shortId - (*) An ID that is often an abbreviation of the plugin's name and used to prefix classes, functions, etc.
• name - (*) The human-friendly name of the plugin.
• description - The plugin's description.
• version - The plugin's current version.
• url - The URL to the plugin's homepage.
• author:
  • name - The name of the plugin's author.
  • url - The URL to the website of the plugin's author.
• textDomain - The plugin's text domain.
• domainPath - The path to the plugin's languages folder.
• minPhpVersion - The minimum PHP version required to run the plugin.
• minWpVersion - The minimum WordPress version required by the plugin.
• extra - A child object that can contain any additional data that you want to have access to from your modules.

(*) All properties are optional, but we strongly recommend that you specify the ones marked with an asterisk.

Example:

{
  "slug": "the-awesome-plugin",
  "shortId": "tap",
  "name": "The Awesome Plugin",
  "description": "A plugin that does awesome things",
  "version": "0.1",
  "url": "https://example.com",
  "author": {
    "name": "John Doe",
    "url": "https://john-doe.blog"
  },
  "textDomain": "tap",
  "minPhpVersion": "7.3",
  "minWpVersion": "5.3",
  "extra": {
    "docsUrl": "https://tap.readthedocs.org",
    "supportUrl": "https://wordpress.org/support/plugins/the-awesome-plugin"
  }
}

Data Duplication

The plugin header in the plugin's main file is required by WordPress. With the addition of a plugin.json file, the plugin's metadata would be present in two separate files. This duplication is not ideal.

At RebelCode, we circumvent this by not having a plugin main file at all. This file is generated from a template as part of the build process, and is not included in the repository. This way, the source-of-truth for our plugin's metadata is the plugin.json file.

Well, technically we generate the plugin.json file as well. If you're interested in seeing how we do this, take a look at our WordPress-plugin-specific build tool, Mantle.

If not, remember that this file is optional. The SDK can be used without it.