Полное руководство по использованию файла WordPress functions.php

0 ∞

В PHP functions.php помещается функционал, необходимый вашей теме и который не относится лишь к конкретному шаблону.

В Кодексе WordPress дается следующее определения файла функций:
Файл functions.php ведет себя, как плагин, добавляя функции и функционал на WordPress- сайт. Его можно использовать для вызова как PHP-функций, так и встроенных функций WordPress, для определения собственных функций. Можно получить тот же результат, добавив код в плагин WordPress или в файл functions.php темы WordPress.

Между functions.php и файлом плагина существует сходство. Он используется для кода того же типа, который можно добавить в плагин.

Если у вас есть много функционального кода, который необходимо использовать на сайте, тогда нужно поместить этот код в плагин. Но если код зависит от темы, то functions.php - это именно то место, где его следует разместить. Общее правило:

Используйте functions.php, когда нужно добавить простые функции, связанные с отображением контента (т. е. он не будет работать, если данная тема неактивна).

Создайте плагин, если функционал более сложный или public function PHP не зависят от темы. В качестве примера можно привести регистрацию типов записей - вы ведь не хотите потерять пользовательские типы записей при изменении темы.

Содержание

Общее использование файла функций

Когда использовать functions.php:

  • Добавление поддержки темы, например, для размещенных изображений, форматов записей и ссылок RSS;
  • Указание WordPress, где находится файл перевода темы;
  • Регистрация расположений для меню навигации, позволяющая добавлять меню через панель администрирования;
  • Добавление, удаление или переопределение функциональных возможностей родительской темы с использованием дочерней темы.
  • В этой статье я покажу вам, как это делается.

Добавление кода в файл функций и его активация

Мы добавляем код в functions.php и указываем WordPress активировать его точно так же, как и в случае с плагином:

  • Пишем функции, которые затем вызываем в файлах шаблонов темы - это полезно, когда есть блок кода, который нужно использовать в нескольких местах темы, но он не будет работать как часть шаблона;
  • Привязываем функции к хуку действия или фильтра. Таким образом, функция запускается, когда WordPress встречает этот хук. WordPress сам предоставляет в распоряжение разработчиков сотни хуков. Вы можете найти некоторые из них в своей теме и плагинах. Если вы добавляете в functions.php код для активации определенного функционала в новой теме, тогда вам нужно создать дочернюю тему. Иначе файл функций будет перезаписан сразу после обновления темы;
  • Создаем шорткод, который затем добавляем в контент. Я бы не рекомендовала добавлять шорткод с помощью файла PHP function. Лучше сделать это с помощью плагина, чтобы содержимое, выводимое шорткодом, не пропало, если вы поменяете тему;
  • Создаем виджет. Это не очень хорошее решение; если вы хотите создать виджет, добавьте для него плагин;
  • Давайте рассмотрим, как работать с файлом functions.php и как с его помощью добавить некоторые из распространенных функциональных возможностей.
Полное руководство по RSS и его использованию в WordPress

Создание файла функций

Если ваша тема не содержит functions.php, его нужно создать в корневом каталоге. Затем нужно добавить в файл открывающийся тег PHP, но закрывать его не нужно:

<?php

Теперь ваш файл функций готов к добавлению кода. Лучше добавлять перед каждым разделом большие блоки закомментированного текста, чтобы легко найти любой код:

/************************************************************************
my_function - короткий текст, описывающий, что это делает
************************************************************************/

Добавление кода в файл functions.php

Рассмотрим некоторые часто используемые функции.

Добавление поддержки темы

В WordPress есть определенные PHP static function, для которых нужно добавить поддержку темой, чтобы воспользоваться ими:

  • Форматы записей - tumblr-форматы, такие как standard, video, quote и aside;
  • Миниатюры записей - если вы хотите использовать их в своей теме, придется добавить код для их вывода в файлах шаблонов. Но они не будут доступны в панели администрирования, если вы не добавите для них поддержку темой;
  • Пользовательский фон - позволяет настраивать фоновое изображение и цвета фона через пользовательский интерфейс;
  • Пользовательский заголовок, который работает так же, как и пользовательский фон;
  • Автоматические ссылки на каналы - для RSS-каналов;
  • HTML5 - для формы поиска, комментариев, галереи и т.д. Это не влияет на возможность создания кода темы с помощью HTML5, но относится к коду, сгенерированному WordPress;
  • Тег заголовка - позволяет добавить тег заголовка в раздел для улучшения SEO и доступности.

Таким образом, чтобы добавить, например, поддержку темы для форматов записей, необходимо использовать функцию add_theme_support():

add_theme_support( 'post-formats' );

Некоторые из функций WordPress functions php, для которых добавляется поддержка темой, имеют дополнительные параметры. Например, при добавлении поддержки можно указать форматы записей, которые хотите использовать:

add_theme_support( 'post-formats', array( 'aside', 'quote' ) );

А для специальных изображений можно указать, в каких типах записей они будут поддерживаться:

add_theme_support( 'post-thumbnails', array( 'post', 'page' ) );

Но ничего из этого не сработает, если вы не поместите свой код внутри функции и не привяжете к соответствующему хуку действия after_setup_theme. Можно добавить все функции add_theme_support() внутри одной более крупной функции, которую вы затем привяжете к after_setup_theme. Поэтому, если вы хотите добавить поддержку темой миниатюр записей, форматов записей, HTML5 и автоматических ссылок на каналы, добавьте следующий код в файл функций:

/*******************************************************************************
wpmu_theme_support - добавляет поддержку темой форматов записей, миниатюр записей, HTML5 и автоматических ссылок на каналы
*******************************************************************************/
function wpmu_theme_support() {

  /* форматы записей */
  add_theme_support( 'post-formats', array( 'aside', 'quote' ) );

  /* миниатюры записей */
  add_theme_support( 'post-thumbnails', array( 'post', 'page' ) );

  /* HTML5 */
  add_theme_support( 'html5' );

  /* автоматические ссылки на каналы */
  add_theme_support( 'automatic-feed-links' );

}
add_action( 'after_setup_theme', 'wpmu_theme_support' );
Полное руководство по использованию постоянных ссылок WordPress

Добавление файла перевода

Перевод означает, что любой текст, который вы добавляете в панель администрирования через тему, будет переведен с использованием файла перевода.

С помощью private function PHP load_theme_textdomain() в файле функций укажите WordPress, где размещается файл перевода:

function wpmu_translation() {
    load_child_theme_textdomain( 'wpmu-theme', get_stylesheet_directory() . '/languages' );
}
add_action( 'after_setup_theme', 'wpmu_translation' );

Эта функция использует функцию get_template_directory(), чтобы найти папку темы, а затем ищет в папке languages файл, начинающийся с wpmu-theme. Поэтому путь будет wp-content/themes/mytheme/languages/, а имя для файла языка начинается с wpmu-theme, за чем следует код языка.

Регистрация меню навигации

В файле functions.php также регистрируются меню навигации. Во многих темах есть флажок «Основное меню», который можно установить в разделе «Меню». Это дает возможность использовать меню в определенном месте темы. Чтобы реализовать подобный функционал, нужно использовать функцию register nav menus():

function wpmu_nav_menus() {
  register_nav_menus( array(
	  'primary' => __( 'Primary Navigation', 'wpmu-theme' ),
	) );
	
}
add_action( 'after_setup_theme', 'wpmu_nav_menus' );

Этот код регистрирует расположение меню, которое будет отображаться в панели администрирования как "Основное меню", а его идентификатор будет primary. Затем вы используете этот идентификатор для вывода меню в файле темы header.php.

Обратите внимание: в коде, приведенном выше, я уже сделала название меню готовым к переводу. Поэтому любой пользователь, говорящий на другом языке, будет видеть текст «Основное меню», переведенным для него с помощью файла перевода.

Также можно использовать эту PHP function для регистрации нескольких позиций вывода меню навигации. В приведенном ниже коде зарегистрировано основное меню, а также дополнительное меню в боковой панели:

function wpmu_nav_menus() {
  register_nav_menus( array(
	  'primary' => __( 'Primary Navigation', 'wpmu-theme' ),
	  'sidebar' => __( 'Sidebar Navigation', 'wpmu-theme' ),
	) );
	
}
add_action( 'after_setup_theme', 'wpmu_nav_menus' );

Нужно добавить код меню в файл sidebar.php темы, используя функцию wp_nav_menu().

Подведем итоги

Все функции, которые я описала выше, активируются с помощью одного хука действия: after_setup_theme. Это означает, что вместо написания нескольких отдельных функций, можно добавить их все в одну функцию, а затем активировать ее с помощью хука.

Можно создать одну большую функцию:

/**********************************************************************************
wpmu_theme_setup - задает настройки темы
- добавляет поддержку темой форматов записей, миниатюр записей, HTML5 и автоматических ссылок на каналы
- регистрирует файл перевода
- регистрирует меню навигации
**********************************************************************************/
function wpmu_theme_setup() {
  /*******************************
  Начинаем с добавления поддержки темой
  *******************************/
  /* форматов записей */
  add_theme_support( 'post-formats', array( 'aside', 'quote' ) );

  /* миниатюр записей */
  add_theme_support( 'post-thumbnails', array( 'post', 'page' ) );
  /* HTML5 */
  add_theme_support( 'html5' );
  /* автоматических ссылок на каналы */
  add_theme_support( 'automatic-feed-links' );
  /*******************************
  Файл перевода
  *******************************/
  load_child_theme_textdomain( 'wpmu-theme', get_stylesheet_directory() . '/languages' );

  /*******************************
  Меню навигации
  *******************************/
  register_nav_menus( array(
	  'primary' => __( 'Primary Navigation', 'wpmu-theme' ),
	  'sidebar' => __( 'Sidebar Navigation', 'wpmu-theme' ),
	) );

}
add_action( 'after_setup_theme', 'wpmu_theme_support' );
WordPress: 10 трюков для файла functions.php

В моей функции добавлено много комментариев, поэтому пользователю легко разобраться, что происходит. Это упростит задачу, если в будущем нужно будет изменить или переопределить функцию WordPress functions php.

Включение файлов

Иногда functions.php становится трудно управляемым, и содержит блоки кода, которые хотелось бы хранить отдельно. В этом случае рекомендуется создать отдельные файлы, а затем вызвать их из functions.php.

Создайте в своей теме папку под названием includes, а затем добавьте в нее отдельные файлы PHP для каждого блока кода, который нужно отделить. Например, если нужно было переместить настройку темы в другой файл, я бы переместила весь приведенный выше код в файл с именем theme_setup.php, а затем вызвала его в functions.php:

include( get_stylesheet_directory() . '/includes/theme_setup.php' );

Данный код вызывает код включаемого файла, а затем запускает его в том месте functions.php, в котором я добавила функцию include(). Обычно я помещаю все включаемые файлы в начале файла функций, чтобы их было легко найти.

Работа с родительскими и дочерними темами

functions.php может стать эффективным инструментом для работы с родительскими и дочерними темами. В дочерней теме можно использовать собственный файл функций для переопределения или удаления функций из родительской темы, или для добавления новых.

Существует три способа переопределения или добавления функций в дочернюю тему:

  • Создание новой версии подключаемой функции;
  • Деактивация функции родительской темы;
  • Добавление собственной функции с использованием приоритета, чтобы переопределить функцию родительской темы.

Рассмотрим каждый из способов.

Подключаемые функции

Если вы работаете с хорошо проработанной родительской темой, то существует вероятность того, что в functions php (где находятся функции) они будут подключаемыми.

Например:

<?php
if ( ! function_exists ( 'my_function' ) ) {
    function my_function() {
        // Содержимое функции.
    }
}
?>

Функции дочерней темы выполняются раньше, чем те, которые содержит родительская тема. Если вы создаете в дочерней теме функцию с тем же именем, WordPress не будет запускать ее из родительской темы. Поэтому для переопределения родительской темы просто создайте в functions.php дочерней темы собственную функцию с тем же именем.

Деактивация функций

Чтобы деактивировать функцию, открепите ее от действия или фильтра, к которому она привязана. Например, если в родительской теме есть функция parent_function(), которая активируется с помощью хука init, можно деактивировать ее в дочерней теме следующим образом:

remove_action( 'init', 'parent_function' );

Это будет означать, что данная функция WordPress functions PHP больше не будет выполняться. Затем, если вы хотите иметь разные функции в дочерней теме, можно написать новую функцию. А затем привязать ее к тому же хуку, но не задавать для нее то же имя.

Примечание. Если родительская функция содержит параметр приоритета в add_action() выполняющей функцию, которую нужно деактивировать, вам нужно указать тот же приоритет при ее деактивации.

Использование приоритета функции

Последний вариант - создать новую функцию с более высоким приоритетом, чем функция, которую нужно переопределить. То есть она будет выполняться после первоначальной функции. Вы должны сделать это, потому что по умолчанию WordPress запускает функции дочерней темы первыми. Только добавив номер приоритета, можно изменить это.

Допустим, что родительская тема содержит функцию parent_function(), которая активируется с помощью хука init с приоритетом 20:

function parent_function() {
    // Содержимое функции.
}
add_action( 'init', 'parent_function', 20 );

Можно написать функцию, которая переопределит родительскую функцию, а затем привязать ее к хуку init с более высоким приоритетом, например 30:

function child_function() {
    // Содержимое функции.
}
add_action( 'init', 'child_function', 30 );

Если родительская функция не имеет приоритета, то она будет использовать значение по умолчанию, равное 10. Таким образом, можно использовать любое число больше 10, чтобы функция дочерней темы выполнялась после родительской функции.

Файл функций - ваш друг

Файл PHP function темы работает очень похоже на плагин, но он специфичен для конкретной темы. Поэтому необходимо использовать его только для того, чтобы добавить функционал, который может быть отключен при активации другой темы. В этой статье вы узнали, для чего используется файл функций темы. Работайте с functions.php осторожно, избегайте его использования, когда все что нужно можно сделать с помощью плагина.