get_file_data() │ WP 2.9.0

Gets the file data specified in the PHP comments of the file.

Looks for metadata in first 8kiB (6000-8000 characters) of file content. The metadata must be specified in a multi-line PHP comment (/* metadata */) as it is done in any WP plugin or theme main file. Each piece of data must be on a separate line. There should be no line breaks in the values, because the value is taken before the first break. See example 1.

So if file data not exists within the first 8kiB, then the author of the plugin/themes needs to fix file and move the data to the top.

This function is defined early in the WordPress loading phase, even before the SHORTINIT constant.

Used By: validate_plugin_requirements(), get_plugin_data()

1 time — 0.000001 sec (speed of light) | 50000 times — 0.61 sec (very fast) | PHP 7.4.8, WP 5.6

Hooks from the function

extra_(context)_headers

Return

String[]. An array of received data from the file header in the format: Key => Value.

Usage

get_file_data( $file, $default_headers, $context );

$file(string) (required)

Absolute path to the file.

$default_headers(array) (required)

The list of values the function should return, in the format: [ $field => $regex ], where:

$field - index of the returned array, which represent $regex found value.
$regex - part of the regular expression responsible for the data-name you want to get value of. For example, if you specify here Description, then the regular expression for the search will take this form: '/^[ \t\/*#@]*Description:(.*)$/mi'.

The value specified in $regex is handled by preg_quote(), so any special characters in the regular expression will be escaped.

$context(string)

If specified, the extra_(context)_headers hook will be triggered, through which the $default_headers parameter can be added.
Default: ''

Examples

#1 Get plugin data

Let's say we created a plugin and in the main file it has the following comments:

/*
Plugin Name: Name
Description: Description
Author: Kama
Version: 1.0
*/

Now let's see how the function works:

// Path to the main plugin file.
// You can get it from the file using the __FILE__ magic constant
$file = '/home/example.com/wp-content/plugins/myplugin/index.php';

$get_headers = [
	'ver' => 'Version',
	'author' => 'Author',
	'name' => 'Plugin Name',
];

$data = get_file_data( $file, $get_headers );

/* $data will contain:
Array (
	[ver] => 1.0
	[author] => Kama
	[name] => Title
)
*/

#2 Dynamic plugin version

Suppose we are writing a plugin and we have a constant PLUGIN_VERSION. Every time we change the version of the plugin in the comments, we need not to forget to change it in the constant. This inconvenience can be bypassed by using this function.

To do this, use the function at the very beginning of the plugin under the comments:

/*
 * Plugin Name: Name of the plugin
 * Plugin URI:  http://wp-kama.com
 * Description: Description of the plugin
 * Author:      Kama
 * Version:     1.0
 */

$data = get_file_data( __FILE__, [ 'ver' => 'Version' ] );

define( 'PLUGIN_VERSION', $data['ver'] );

#3 Register stylesheet and scripts

/**
 * Register stylesheet and scripts
 * Set the version of each the version of the plugin.
 */
function register_plugin_styles_scripts() {

	// Set the file path to a variable.
	$file_path = plugin_dir_path( __DIR__ ) . 'example-plugin-file.php';

	// Read the version number from the main plugin file then set it to a variable.
	$plugin_data = get_file_data( $file_path, [ 'Version' => 'Version' ] );

	if ( ! empty( $plugin_data['Version'] ) ) {

		// The the value of the Version header to a variable.
		$ver = $plugin_data['Version'];

		// Use the variable, $ver, in more than one stylesheet/script
		// to bust cache when the plugin gets updated.
		wp_enqueue_style( 'public-style', plugins_url( 'path/to/stylesheet.css' ), [], $ver );
		wp_enqueue_script( 'public-script', plugins_url( 'path/to/script.js' ), [], $ver , true );
	}

}

Changelog

Since 2.9.0

Introduced.

Code of `get_file_data() get file data` ^{WP 6.0.1}

wp-includes/functions.php

function get_file_data( $file, $default_headers, $context = '' ) {
	// Pull only the first 8 KB of the file in.
	$file_data = file_get_contents( $file, false, null, 0, 8 * KB_IN_BYTES );

	if ( false === $file_data ) {
		$file_data = '';
	}

	// Make sure we catch CR-only line endings.
	$file_data = str_replace( "\r", "\n", $file_data );

	/**
	 * Filters extra file headers by context.
	 *
	 * The dynamic portion of the hook name, `$context`, refers to
	 * the context where extra headers might be loaded.
	 *
	 * @since 2.9.0
	 *
	 * @param array $extra_context_headers Empty array by default.
	 */
	$extra_headers = $context ? apply_filters( "extra_{$context}_headers", array() ) : array();
	if ( $extra_headers ) {
		$extra_headers = array_combine( $extra_headers, $extra_headers ); // Keys equal values.
		$all_headers   = array_merge( $extra_headers, (array) $default_headers );
	} else {
		$all_headers = $default_headers;
	}

	foreach ( $all_headers as $field => $regex ) {
		if ( preg_match( '/^(?:[ \t]*<\?php)?[ \t\/*#@]*' . preg_quote( $regex, '/' ) . ':(.*)$/mi', $file_data, $match ) && $match[1] ) {
			$all_headers[ $field ] = _cleanup_header_comment( $match[1] );
		} else {
			$all_headers[ $field ] = '';
		}
	}

	return $all_headers;
}