Latest revision as of 20:54, 11 September 2021

Languages: English • 日本語 Português do Brasil • (Add your language)

In WordPress Themes and Plugins consist of one or more files of which one has (Drop-Ins, Must-Use-Plugins: can have) so called File Headers containing meta-information (Name, Version, Author, ...) regarding the concrete Theme or Plugin.

File Headers are placed inside a block in the beginning of the file (not necessarily starting on the very first line), one header per line. A Header consists of a Name and a Value.

File Header Examples

The following file header examples are taken out of example theme and plugin files that do ship with WordPress or are closely related to the WordPress project (Default Theme and Core Plugin):

Plugin File Header Example

This is an example for the health-check.php file, part of the Health Check plugin:

<?php
/*
Plugin Name: Health Check
Plugin URI: https://wordpress.org/plugins/health-check/
Description: Checks the health of your WordPress install
Version: 0.1.0
Author: The Health Check Team
Author URI: http://health-check-team.example.com
Text Domain: health-check
Domain Path: /languages
*/

Here's another example which allows file-level PHPDoc DocBlock as well as WordPress plugin file headers:

<?php
/**
 * Plugin Name
 *
 * @package     PluginPackage
 * @author      Your Name
 * @copyright   2019 Your Name or Company Name
 * @license     GPL-2.0-or-later
 *
 * @wordpress-plugin
 * Plugin Name: Plugin Name
 * Plugin URI:  https://example.com/plugin-name
 * Description: Description of the plugin.
 * Version:     1.0.0
 * Author:      Your Name
 * Author URI:  https://example.com
 * Text Domain: plugin-slug
 * License:     GPL v2 or later
 * License URI: http://www.gnu.org/licenses/gpl-2.0.txt
 */

Theme File Header Example

These are the very first lines of a the style.css file part of the Twenty Thirteen theme:

/*
Theme Name: Twenty Thirteen
Theme URI: http://wordpress.org/themes/twentythirteen
Author: the WordPress team
Author URI: http://wordpress.org/
Description: The 2013 theme for WordPress takes us back to the blog, featuring a full range of post formats, each displayed beautifully in their own unique way. Design details abound, starting with a vibrant color scheme and matching header images, beautiful typography and icons, and a flexible layout that looks great on any device, big or small.
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: black, brown, orange, tan, white, yellow, light, one-column, two-columns, right-sidebar, flexible-width, custom-header, custom-menu, editor-style, featured-images, microformats, post-formats, rtl-language-support, sticky-post, translation-ready
Text Domain: twentythirteen

This theme, like WordPress, is licensed under the GPL.
Use it to make something cool, have fun, and share what you've learned with others.
*/

List of Header Names

The following is a list of Header-Names that are currently used by Themes and Plugins in the current concrete File Header default implementation (02 Jun 2010). Headers can be extended, so this is a subset, not the superset:

Plugin

• Author (Plugin)
• Author URI (Plugin)
• Description (Plugin)
• Domain Path (Plugin)
• Network (Plugin)
• Plugin Name (Plugin)
• Plugin URI (Plugin)
• Site Wide Only (Plugin; deprecated in favor of Network)
• Text Domain (Plugin)
• Version (Plugin)

Theme

• Author (Theme)
• Author URI (Theme)
• Description (Theme)
• Domain Path (Theme)
• Status (Theme)
• Tags (Theme)
• Template (Theme)
• Text Domain (Theme)
• Theme Name (Theme)
• Theme URI (Theme)
• Version (Theme)

Page Template

• Template Name
• Description (cf. twentyeleven)

For a description of some of the Plugin Headers, please see Plugin File Headers, For Theme Headers please see Theme Stylesheet.

If you are unable to find a concrete specification for the one or other header, you need to read the WordPress source-code to find out more specific information about them (please see File Header Related Functions below for a list of related functions and hooks).

File Header Filenames

Since multiple files in a plugin/theme can contain meta information, the following are the file-names and the order (from top to bottom) of which files are parsed for headers.

Plugin

1. Each PHP-file in the directory order. If a file does not contain the Name header, it won't be treated as a plugin.

Theme

1. The style.css CSS-file

Must-Use Plugin

1. The concrete PHP-file

Drop-In

1. The concrete PHP-file

File Header Specification

Per de-facto implementation, File Headers can be specified as the following:

1. Header are written in a block in the beginning of a PHP or CSS file.
2. A block might be placed in a files comment, like a PHP or CSS comment.
3. The whole header block must be placed inside the first 8 192 bytes of the file.
4. Headers follow up to each other, one on it's own line.
5. A header consists of a name and a value.
6. Name and value are separated by the ':' character.
7. The name has a minimum of one, and a maximum of three words.
8. The minimum length of a word is three, the maximum length is 12 characters.
9. A word consists of the characters a-z and A-Z.
10. Words are separated by a single space (d32/x20)
11. A name starts after the beginning of a line or after a whitespace character.
12. A name ends before the ':' character.
13. A value starts after the ':' character.
14. Sometimes the ':' character is suffixed by a space. This space is considered to not be part of the value.
15. A header-value can contain any characters but not a newline.
16. Header values might become filtered before they are used.
17. Header values can but must not contain HTML code in form of certain XHTML Elements or HTML Tags.

Note: Because of the nature that there are individual headers, the maximum number of words as well as the minimum and maximum number of characters per word are based on default headers. Because this is a subset and not the superset of all header names, this might vary depending on the implementation and plugins you are using.

File Header Related Functions

The File Header API consists of all functions regarding theme and plugin file headers and related hooks (actions, filters).

• get_file_data()
• wp_get_theme()
• get_plugin_data()
• _get_plugin_data_markup_translate()
• _cleanup_header_comment()
• Filter: extra_*_headers (e.g.: extra_theme_headers, extra_plugin_headers)

Header Context

Some of the API functions provide the possibility to add a context to headers. There are two contexts defined in the wordpress core code: Themes ('theme') and Plugins ('plugin').

File Headers in readme.txt

Some plugins contain the readme.txt file which might contain look-a-like headers as well. Those files are not handled by WordPress but by third-party applications. Because those applications can be quite popular, I note down here those tags from an example readme file:

Contributors: markjaquith, mdawaffe (this should be a list of wordpress.org userid's)
Donate link: http://example.com/
Tags: comments, spam
Requires at least: 2.0.2
Tested up to: 2.1
Stable tag: 4.3

As ticket #12260 suggests, the headers from readme.txt are used through remote WP.org API calls. This is a good example of how third party applications use has direct impact on wordpress core code usage.