Получение метаданных файла с помощью функции GET_FILE_DATA()

# Функция GET_FILE_DATA() │ WP 2.9.0

Функция GET_FILE_DATA() извлекает информацию о файле, которая указана в комментариях PHP самого файла.

## Как это работает?

Эта функция ищет метаданные в первых 8 килобайтах (6000-8000 символов) содержимого файла. Метаданные должны быть записаны в многострочном комментарии PHP (/* метаданные */), как это делается в главном файле любого плагина или темы WordPress. Каждое значение должно находиться на отдельной строке. Не должно быть переносов строк внутри значений, так как значение будет прочитано до первого переноса. Посмотрите на пример 1.

Если метаданные отсутствуют в первых 8 килобайтах, разработчику плагина или темы нужно исправить файл и перенести данные в начало.

Эта функция определяется на ранних этапах загрузки WordPress, даже до константы SHORTINIT.

### Используют

Функцию GET_FILE_DATA() используют следующие функции:
- validate_plugin_requirements()
- get_plugin_data()

### Производительность

- 1 раз — 0.0000751 сек (очень быстро)
- 50000 раз — 0.46 сек (очень быстро)

*Для PHP 7.4.25, WP 6.0.3*

## Хуки функции

- extra_(context)_headers

## Возвращаемое значение

Функция возвращает массив строк с данными из заголовка файла в формате: Ключ => Значение.

## Как использовать

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

• $file (строка) — обязательный параметр. Абсолютный путь к файлу.

• $default_headers (массив) — обязательный параметр. Список значений, которые функция должна вернуть в формате: [ $field => $regex ], где:

  • $field — индекс возвращаемого массива, который будет представлять значение, найденное по $regex.
  • $regex — часть регулярного выражения, отвечающая за нужное имя данных. Например, если вы укажете "Description", то регулярное выражение примет вид: '/^[t/*#@]*Description:(.*)$/mi'.

Значение, указанное в $regex, обрабатывается функцией preg_quote(), так что любые специальные символы в регулярном выражении будут экранированы.

• $context (строка) — если указан, будет вызван хук extra_(context)_headers, через который можно добавить параметр $default_headers.
  • По умолчанию: ''

Примеры

Пример 1: Получение данных плагина

Допустим, мы создали плагин, и в главном файле у него есть следующие комментарии:

/*
Plugin Name: Имя
Description: Описание
Author: Kama
Version: 1.0
*/

Теперь давайте посмотрим, как работает функция:

// Путь к главному файлу плагина. 
$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 будет содержать:
Array (
    [ver] => 1.0
    [author] => Kama
    [name] => Имя
)
*/

Пример 2: Динамическая версия плагина

Предположим, мы пишем плагин, и у нас есть константа PLUGIN_VERSION. Каждый раз, когда мы изменяем версию плагина в комментариях, нам нужно не забыть обновить её и в константе. Эту проблему можно решить с помощью этой функции.

Для этого используем функцию в самом начале плагина под комментариями:

/*
 * Plugin Name: Имя плагина
 * Plugin URI:  http://wp-kama.com
 * Description: Описание плагина
 * Author:      Kama
 * Version:     1.0
 */

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

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

Пример 3: Регистрация стилей и скриптов

/**
 * Регистрация стилей и скриптов
 * Устанавливает версию плагина.
 */
function register_plugin_styles_scripts() {
    // Устанавливаем путь к файлу в переменную.
    $file_path = plugin_dir_path( __DIR__ ) . 'example-plugin-file.php';

    // Читаем номер вер��ии из главного файла плагина и устанавливаем в переменную.
    $plugin_data = get_file_data( $file_path, [ 'Version' => 'Version' ] );

    if ( ! empty( $plugin_data['Version'] ) ) {
        // Значение заголовка версии устанавливаем в переменную.
        $ver = $plugin_data['Version'];

        // Используем переменную $ver в нескольких стилях/скриптах
        // для сброса кэша при обновлении плагина.
        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 );
    }
}

Список изменений

Начало поддержки с версии 2.9.0.

Код функции GET_FILE_DATA()

function get_file_data( $file, $default_headers, $context = '' ) {
    // Загружаем только первые 8 КБ файла.
    $file_data = file_get_contents( $file, false, null, 0, 8 * KB_IN_BYTES );

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

    // Убедимся, что мы учитываем только символы перевода строки.
    $file_data = str_replace( "r", "n", $file_data );

    // Фильтрация дополнительных заголовков файла по контексту.
    $extra_headers = $context ? apply_filters( "extra_{$context}_headers", array() ) : array();

    if ( $extra_headers ) {
        $extra_headers = array_combine( $extra_headers, $extra_headers ); // Ключи равны значениям.
        $all_headers   = array_merge( $extra_headers, (array) $default_headers );
    } else {
        $all_headers = $default_headers;
    }

    foreach ( $all_headers as $field => $regex ) {
        if ( preg_match( '/^(?:[ t]*