I’m looking at adding a few more explanatory documents to the plugin guidelines; this is the first of them covering the requirements for the plugin header. When this document is finalised, I can do the one for the plugin readme.txt and then follow up with documents for the future theme guidelines.
Plugin Header Requirements
The main PHP file of a plugin must contain certain header informaiton which tells ClassicPress that i is a plugin and provides information about the plugin.
There are several fields which are required to be included in the plugin header (there is an overlap with the content of the readme.txt):
-
Plugin Name
(String). Name of the plugin. Should be unique.
-
Plugin URI
(String). The plugins home page, which should be a unique page, ideally on your own site or in the GitHub repository.
-
Description
(String). A short description, no more than 140 characters) of the plugin which will be displayed in the ClassicPress Admin.
-
Version
(String). The current version of the plugin (e.g. 1.0.3 or 2.1.1); for ClassicPres plugins the version should follow semver.
-
Author
(String). Name of the plugin author; multiple authors ay be listed, separated with commas.
-
Author URI
(String). The author's website or ClassicPress Forum profile.
There are additional fields which can optionally be included:
-
Text Domain
(String). The gettext text domain of the plugin. This should be unique per plugin and should be same as the one used in load_plugin_textdomain().
-
Domain Path
(String). The folder location of the translations; this is only required if the translations are not stored in the root of the plugin directory. For example, if .mo files are located in the languages folder then Domain Path will be "/languages/" and must have the first slash.
-
Network
(Boolean). "true" if the plugin is activated across all sites in an installation; this prevents the plugin being activated on a siet when Multisite is enabled. If this will not be "true" then the line should be excluded.
License
(String). The shortname of the applied license, such as "GPLv2 or later". All plugins submitted to the ClassicPress Plugin Directory must be licensed under the GPL.
License URI
(String). A link to the full text of the license, such as http://www.gnu.org/licenses/gpl-2.0.html.
This is an example of how a plugin header might look:
/*
Plugin Name: My Plugin
Plugin URI: https://www.example.com/plugins/my-plugin/
Description: My plugin has this functionality.
Version: 1.0.0
Author: John Smith
Author URI: https://www.example.com/authors/john-smith/
License: GPLv2
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: john-smith-my-plugin
Domain Path: /languages/
*/
2 Likes
I based the required fields on the get_plugin_data function.
I don’t know if there is a negative impact if the field isn’t there? If not, then it might make sense to remove the Author URI, although as the doc mentions they could point it to their forum profile.
1 Like
I know you had a reason. Just putting in my .02 because, well, it only cost .02. 
Sorry, edited my last comment as you responded.
I don’t think it’s a huge issue if it’s not there; it just makes the plugin’s admin row (and modal window) not as fleshed-out. I think it’s fine to point at a forum profile.
I fixed a few typos, and added some clarification.
Plugin Header Requirements
The main PHP file of a plugin is the one that contains certain header information which tells ClassicPress that it is a plugin, and provides information about the plugin. ClassicPress only supports plugin files in the base plugins directory (wp-content/plugins) and in one directory above the plugins directory (wp-content/plugins/my-plugin). The file it looks for has the plugin data and must be found in one of those two locations.
There are several fields which are required to be included in the plugin header (there is an overlap with the content of the readme.txt). All plugin data must be on its own line. For plugin description, it must not have any newlines.
-
Plugin Name Name of the plugin; should be unique.
-
Description A short description, no more than 140 characters) of the plugin which will be displayed in the ClassicPress Admin.
-
Version The current version of the plugin (e.g. 1.0.3 or 2.1.1); for ClassicPress plugins the version should follow semantic versioning.
-
Author Name of the plugin author; multiple authors may be listed, separated with commas.
There are additional fields which can optionally be included:
-
Plugin URI The plugin’s home page, which should be a unique page, ideally on your own site or in the GitHub repository.
-
Author URI The author’s website or ClassicPress Forum profile.
-
Text Domain The gettext text domain of the plugin. This should be unique per plugin and should be same as the one used in load_plugin_textdomain().
-
Domain Path The folder location of the translations; this is only useful if the translations are located in a folder above the plugin’s base path. For example, if .mo files are located in the languages folder then Domain Path will be “/languages/” and must have the first slash.
-
Network Specify true if the plugin is activated across all sites in an installation. This prevents the plugin being activated on a single site when Multisite is enabled. If this will not be “true” then the line should be omitted.
License The short name of the applied license, such as “GPLv2 or later”. All plugins submitted to the ClassicPress Plugin Directory must have a GPL compatible license.
License URI A link to the full text of the license, such as http://www.gnu.org/licenses/gpl-2.0.html.
This is an example of how a plugin header might look:
/*
Plugin Name: My Plugin
Plugin URI: https://www.example.com/plugins/my-plugin/
Description: My plugin has this functionality, and although this is a long description, it contain no newline characters.
Version: 1.0.0
Author: John Smith
Author URI: https://www.example.com/authors/john-smith/
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Text Domain: john-smith-my-plugin
Domain Path: /languages/
*/
2 Likes
We probably should add these 2 as well I believe?
Requires at least:
Requires PHP:
See also Header Requirements | Plugin Developer Handbook | WordPress Developer Resources
Perhaps CP doesnt yet use them (no idea really) but if it does not, it should, and preparing the plugins now is better than asking them to update later.
The fields I’ve included in the header document are the ones returned by the get_plugin_data function (plus the license ones).
The CP Directory will, I assume, work like the WP Repo is using the Requires… fields from the readme so is there a benefit to having them in the header as well?
Seems like it is just 5.8 that expects those in main file instead of in readme file, whereas before they where in the readme.
@joyously probably knows this better.
Here we go again… WP changed and CP did not. I proposed that we incorporate that change, while trying to explain the difference.
CP core does not currently check the versions, because the update API does that check, and only sends the ones that match. This is why there is a problem of people running old versions of WP. They won’t see that the plugins have an update. WP 5.5 added auto-updates, so they added some version checking into core. This is where they inadvertently put one of the fields in the readme, as a fallback. But that was incorrect, so they removed that in 5.8, and the core version checks use the plugin header fields only.
For CP, it seems that we want to maintain the WP API in core and add the CP API, and the first thought is to make it the same. However, CP auto updates itself and you don’t really run an old version, so the update API would not have that same weirdness as WP, but WP’s API will still only give you info for updates to the version you are asking about. CP does not yet have the version check in core, so those fields are not “required” in plugins like they would be in WP.
1 Like