Файл темы functions.php в WordPress

Каждый знакомый с WordPress слышал про файл темы (шаблона) functions.php. Однако не все хорошо понимают его назначение, видя в нем лишь файл в котором хранятся различные php функции. В сети, как и у меня на этом сайте, часто предлагается добавлять PHP код в этот файл. Однако не каждый код подойдет для этого файла. Не потому что он не будет работать, а потому что он не подходит по логике использования.

Также при редактировании functions.php новички допускают ошибки из-за которых сайт перестает работать.

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

Возможности functions.php

functions.php располагается в папке темы и загружается каждый раз, во время просмотра внешней части сайта, в админ-панели и даже во время AJAX запросов. Нет случая, когда functions.php не будет подключен и это открывает широкие возможности перед разработчиками.

Для примера, следующий код, вставленный в файл темы functions.php расширит возможности темы - включит поддержку миниатюр поста:

add_action( 'after_setup_theme', 'wp_kama_theme_setup' );
function wp_kama_theme_setup(){
	// Поддержка миниатюр
	add_theme_support( 'post-thumbnails' );
}

Другой пример, код заменит текст в подвале админ-панели WordPress, на данные о количестве запросов к базе данных, времени генерации страницы и использовании памяти:

## Данные о количестве запросов к базе данных в подвале админки
add_filter( 'admin_footer_text', 'wp_usage' ); // в админке
add_filter( 'wp_footer', 'wp_usage' );         // на сайте
function wp_usage(){
	echo sprintf(
		__( 'SQL: %d за %s сек. %s MB', 'km' ),
		get_num_queries(),
		timer_stop( 0, 3 ),
		round( memory_get_peak_usage()/1024/1024, 2 )
	);
}

functions.php против плагинов

— «Плагины работают медленнее чем код в файле functions.php», говорят неосведомленные - это не так!

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

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

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

Поэтому, давайте удалим его из functions.php и сделаем из него плагин - это просто!

Чтобы создать плагин нужно создать файл с кодом ниже (название файла может быть любое), добавить его в каталог плагинов wp-content/plugins/ и активировать плагин в админ-панели:

<?php
/**
 * Plugin Name: Здесь любое название плагина
 */

// код плагина

add_filter( 'admin_footer_text', 'wp_usage' );
function wp_usage(){
	echo sprintf(
		__( 'SQL: %d за %s сек. %s MB', 'km' ),
		get_num_queries(),
		timer_stop( 0, 3 ),
		round( memory_get_peak_usage()/1024/1024, 2 )
	);
}

Если нет желания видеть еще один плагин в админ-панели, то можно использовать Must-Use плагины.

Для чего на самом деле нужен functions.php

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

Если на каком-либо ресурсе вам предлагают добавить код в файл functions.php, а функция кода не относится к шаблону непосредственно, то не ленитесь сделайте плагин из этого кода и возможно в будущем избежите неожиданной пропажи добавленного ранее функционала.

Как подгружается functions.php

functions.php подключается во время инициализации текущей темы, после того, как подключены все функции WordPress и все активные плагины. Опишу коротко хронологию загрузки WordPress, где видно, когда подключаются важные файлы:

index.php
	wp-blog-header.php
		wp-load.php
			wp-config.php
				wp-settings.php
					// Подключаются самые базовые функции (подключение к БД $wpdb и система фильтров)
					// Подключаются базовые фильтры

					// SHORTINIT: Остановка загрузки, где есть только самое базовое: if ( SHORTINIT ) return false;

					// подключается вся среда WordPress: базовые функции, фильтры

					// подключаются must-use плагины, затем срабатывает событие:
					do_action( 'muplugins_loaded' );

					// подключаются активированные плагины, затем срабатывает событие:
					do_action( 'plugins_loaded' );

					// устанавливаются глобальные переменные: wp_the_query, wp_query, wp_rewrite, wp, wp_widget_factory, wp_roles ...

					do_action( 'setup_theme' );
					// устанавливается текущая тема
Подключение functions.php дочерней темы
Подключение functions.php родительской темы
					do_action( 'after_setup_theme' );

					// событие, когда среда WP, все плагины и тема полностью подключены, но на экран еще ничего не выведено:
					do_action( 'init' );

					// проверка статуса сайта для мультисайтовой сборки

					// тоже самое что init только после проверки статуса (до этой строки работа PHP может не дойти)
					do_action( 'wp_loaded' );

		wp() // заполняет основной запрос WP и все глобальные переменные связанные с ним

		wp-includes/template-loader.php // подключает нужный файл шаблона

Процесс загрузки WordPress, и functions.php в частности, хорошо показан на этом рисунке:

functions.php дочерней темы

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

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

Ошибки в functions.php при вставке кода

Неоднократно встречал вопросы об ошибках, вроде: "После установки кода в файл functions.php сайт перестал работать - белый экран. Что делать?". Я и сам с подобным сталкивался когда-то.

Для меня некоторые решения этой проблемы, долгое время, оставались загадкой — вроде ничего не делал, и даже танца с бубном не было, но - раз и все заработало. Почему так происходит? Давайте рассмотрим возможные ситуации из-за которых может "ломаться" сайт и их объяснение:

1. Вставляете готовый код — сайт перестает работать.

2. Редактируете functions.php — сайт перестает работать.

Чаще всего, дело в открывающем и закрывающем тегах PHP <?php и ?>. Обычно, если вставляемый код имеет в начале и в конце эти теги, то их нужно удалить. Также, файл functions.php не должен выводить на экран никакой текст (HTML код или другой контент). Вывод текста допускается только внутри функции, которые в дальнейшем будут использоваться в шаблоне или которые прикрепляются к хукам (подробнее см. ниже).

Чтобы не было ошибок, учитывайте 4 момента:

#1 Правильная вложенность

Пример, у нас была такая структура:

<?php
........здесь код.........
?>

Если Вы добавили php код так, то это вызовет ошибку или, что еще хуже, белый экран, когда показ ошибок отключен:

<?php
........здесь код.........
   <?php
   ...... здесь добавленный код ........
   ?>
........здесь код.........
?>

Правильно так:

<?php
........здесь код.........

   ........ здесь добавленный код ........

........здесь код.........
?>

#2 Никаких переносов строк, пробелов, текста до <?php и после ?>

Такой код вызовет ошибку:

<?php
 ...... здесь код ........
?>
<?php
 ...... здесь добавленный код ........
?>

А этот нет:

<?php
 ...... здесь код ........
?><?php
 ...... здесь добавленный код ........
?>

Логичнее его записать так:

<?php
 ...... здесь код ........

 ...... здесь добавленный код ........
?>

Бывает что перенос строки ставят в самом конце functions.php, вот тогда это становится настоящей проблемой, потому что все казалось бы правильно, но сайт не работает. На самом деле после ?> или до <?php присутствуют невидимый символ переноса строки \n. Выглядит такая ошибка, крайне безобидно, вот так:

<?php
... начало файла ...
  ...... здесь код ........
... конец файла ...
?>
здесь пустая строчка

По этой причине многие разработчики вообще удаляют закрывающий тег ?>, это допустимо для PHP. Рекомендую всегда делать именно так:

<?php
... начало файла ...
  ...... здесь код ........
... конец файла ...

#3 Использование <?php и ?> внутри PHP функции

Если в functions.php присутствует функция, то внутри этой функции можно использовать теги <?php и ?>, например, для того, чтобы визуально выделить HTML код внутри функции:

<?php
... начало файла ...

function function_name(){
	?>
		 <div>это html код</div>
	<?php
}

... конец файла ...
?>

Дело в том, что в этом случае функция только лишь регистрируется и не выполняет никаких действий. Все что внутри функции (между { }) не работает пока эта функция не будет вызвана, а вызываются такие функции обычно из шаблона или через фильтры, уже после того как отправлены HTTP заголовки. Поэтому в данном примере, мы можем игнорировать переносы строк и использовать ?> и <?php как угодно.

#4 Кодировка

Еще одна заметка касательно файла functions.php: устанавливайте файлу кодировку UTF-8 (UTF-8 без BOM). Иначе, если функции в файле будет текст на кириллице, то он выведется непонятными символами: кракозябрами, каракулями - называйте как хотите.

—