If you’re a WordPress theme or plugin developer, you’re already familiar with that same block of code you add over and over within your main plugin file or theme’s style.css file. It looks a little something like this:

/**
 * Theme Name: Awesomeness
 * Theme URI: http://themehybrid.com/themes
 * Description: An example theme description.
 * Author: Justin Tadlock
 * Author URI: http://themehybrid.com
 * Version: 0.1
 * Tags: widgets, theme-options
 */

These blocks of code are called file headers in WordPress terminology. WordPress even has an API for getting data from these headers to show information about your plugin/theme.

This tutorial will walk you through the process of adding and using custom file headers. I’ll focus mainly on themes throughout this tutorial as an example, but this technique can be applied to plugins too.

Why customize file headers?

Well, you shouldn’t add custom file headers just for fun, unless you just want to play around with some WordPress code. Custom file headers can be extremely useful if you need to access particular data about your plugin/theme without having to rewrite code over and over.

A good example of where this is useful is some of the currently proposed changes for file headers in WordPress. Two of the proposed changes deal with licensing and the other is for a template (parent theme) version check.

• License: The theme’s license.
• License URI: The theme’s license URI.
• Template Version: The minimum version of the parent theme.

Adding these to your theme’s style.css would look like this:

/**
 * Theme Name: Awesomeness
 * Theme URI: http://themehybrid.com/themes
 * Description: An example theme description.
 * Author: Justin Tadlock
 * Author URI: http://themehybrid.com
 * Version: 0.1
 * Tags: widgets, theme-options
 * Template: news
 * Template Version: 0.2
 * License: GNU General Public License v2.0
 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
 */

A theme (and WordPress if the headers are added to core) could pull this information out and display it. For example, you could display an error message if the Template Version didn’t match up with the parent theme version number, letting the user know that they need to upgrade their parent theme.

These are just a few examples. I’m sure you can think of some other useful file headers for your projects.

How to add custom file headers

In this part of the tutorial, I’m introducing two custom file headers that would work great for both plugins and themes:

• Support URI: The URI to the plugin/theme support forums.
• Documentation URI: The URI to the plugin/theme documentation.

I like these two file headers because they allow me to easily link to my support forums and documentation in places where a user might need that information.

To add these your theme, you need to filter the extra_theme_headers hook as shown in the following code:

add_filter( 'extra_theme_headers', 'my_extra_theme_headers' );

function my_extra_theme_headers( $headers ) {

	if ( !in_array( 'Support URI', $headers ) )
		$headers[] = 'Support URI';

	if ( !in_array( 'Documentation URI', $headers ) )
		$headers[] = 'Documentation URI';

	return $headers;
}

For plugins, the code would be nearly identical. Rather than filtering extra_theme_headers, you’d filter the extra_plugin_headers hook as in the following code.

add_filter( 'extra_plugin_headers', 'my_extra_plugin_headers' );

function my_extra_plugin_headers( $headers ) {

	if ( !in_array( 'Support URI', $headers ) )
		$headers[] = 'Support URI';

	if ( !in_array( 'Documentation URI', $headers ) )
		$headers[] = 'Documentation URI';

	return $headers;
}

At this point, you’ve merely added support of these headers to your theme or plugin. WordPress doesn’t actually do anything with them. That’s up to you.

Adding custom headers

Let’s revisit our original theme style.css file header. To use the custom Support URI and Documentation URI file headers, you need add them to the file header block.

/**
 * Theme Name: Awesomeness
 * Theme URI: http://themehybrid.com/themes
 * Description: An example theme description.
 * Author: Justin Tadlock
 * Author URI: http://themehybrid.com
 * Version: 0.1
 * Tags: widgets, theme-options
 * Support URI: http://themehybrid.com/forums
 * Documentation URI: http://themehybrid.com/codex
 */

You can see that I’ve added two extra lines to the header block:

* Support URI: http://themehybrid.com/forums
* Documentation URI: http://themehybrid.com/codex

Neither WordPress nor our theme/plugin will do anything with this custom data just yet. You still have to pull the information out and use it.

Getting file header data

There are two functions for getting file header data:

• get_theme_data(): Gets a theme file header data.
• get_plugin_data(): Gets a plugin file header data.

Now, let’s pull the custom data from the style.css file from the previous section. Assuming your theme is a regular theme or parent theme, you’d use the following PHP code to get the data.

$theme_data = get_theme_data( trailingslashit( TEMPLATEPATH ) . 'style.css' );

$theme_data will be an array of all the available file headers for the theme. If you wanted to get this information from the child theme, you’d change TEMPLATEPATH to STYLESHEETPATH.

Suppose you wanted to display a link somewhere in your theme settings page back to the theme’s support forums and documentation, your code would look something like the following.

<?php
	$theme_data = get_theme_data( trailingslashit( TEMPLATEPATH ) . 'style.css' );

	if ( !empty( $theme_data['Support URI'] ) ) { ?>
		<a href="<?php echo esc_url( $theme_data['Support URI'] ); ?>">Support</a>
	<?php }

	if ( !empty( $theme_data['Documentation URI'] ) ) { ?>
		<a href="<?php echo esc_url( $theme_data['Documentation URI'] ); ?>">Documentation</a>
	<?php }
?>

That’s all there is to it for themes. If you’re adding custom headers to plugins, note that the get_plugin_data() function is only available in the WordPress admin. You really shouldn’t need it on the front end of the site anyway (for themes or plugins).

Thoughts?

I’ve shown you a few different examples of custom file headers throughout this tutorial. Do you have any that you think would be great additions to WordPress core? Or, just great additions to some plugins or themes?