Организация кода в файле functions.php вашей темы WordPress

Поздний ответ

Как правильно подключать файлы:

function wpse1403_bootstrap()
{
    // Здесь мы загружаем из нашей директории includes
    // Учитываются как родительские, так и дочерние темы    
    locate_template( array( 'inc/foo.class.php' ), true, true );
}
add_action( 'after_setup_theme', 'wpse1403_bootstrap' );

То же самое работает и для плагинов.

Как получить правильный путь или URI

Также обратите внимание на функции API файловой системы, такие как:

• home_url()
• plugin_dir_url()
• plugin_dir_path()
• admin_url()
• get_template_directory()
• get_template_directory_uri()
• get_stylesheet_directory()
• get_stylesheet_directory_uri()
• и другие.

Как уменьшить количество include/require

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

foreach ( glob( 'path/to/folder/*.php' ) as $file )
    include $file;

Имейте в виду, что это игнорирует ошибки (может быть полезно для продакшена)/незагружаемые файлы.

Чтобы изменить это поведение, вы можете использовать другую конфигурацию во время разработки:

$files = ( defined( 'WP_DEBUG' ) AND WP_DEBUG )
    ? glob( 'path/to/folder/*.php', GLOB_ERR )
    : glob( 'path/to/folder/*.php' )

foreach ( $files as $file )
    include $file;

Редактирование: ООП/SPL подход

Вернувшись и увидев, что этот ответ получает все больше голосов, я решил показать, как я делаю это сейчас - в мире PHP 5.3+. Следующий пример загружает все файлы из подпапки темы с именем src/. Здесь находятся мои библиотеки, которые обрабатывают определенные задачи, такие как меню, изображения и т.д. Вам даже не нужно заботиться о имени, так как каждый файл загружается. Если у вас есть другие подпапки в этой директории, они игнорируются.

\FilesystemIterator - это замена \DirectoryIterator в PHP 5.3+. Оба являются частью PHP SPL. В то время как в PHP 5.2 можно было отключить встроенное расширение SPL (менее 1% установок делали это), сейчас SPL является частью ядра PHP.

<?php

namespace Theme;

$files = new \FilesystemIterator( __DIR__.'/src', \FilesystemIterator::SKIP_DOTS );
foreach ( $files as $file )
{
    /** @noinspection PhpIncludeInspection */
    ! $files->isDir() and include $files->getRealPath();
}

Ранее, когда я еще поддерживал PHP 5.2.x, я использовал следующее решение: \FilterIterator в директории src/Filters для получения только файлов (и не точек указателей папок) и \DirectoryIterator для цикла и загрузки.

namespace Theme;

use Theme\Filters\IncludesFilter;

$files = new IncludesFilter( new \DirectoryIterator( __DIR__.'/src' ) );
foreach ( $files as $file )
{
    include_once $files->current()->getRealPath();
}

\FilterIterator был очень простым:

<?php

namespace Theme\Filters;

class IncludesFilter extends \FilterIterator
{
    public function accept()
    {
        return
            ! $this->current()->isDot()
            and $this->current()->isFile()
            and $this->current()->isReadable();
    }
}

Помимо того, что PHP 5.2 уже устарел (как и 5.3), есть тот факт, что это больше кода и еще один файл в игре, поэтому нет причин использовать этот подход и поддерживать PHP 5.2.x.

Итог

РЕДАКТИРОВАНИЕ Очевидно, правильный способ - использовать код с namespace, подготовленный для автозагрузки PSR-4, размещая все в соответствующей директории, которая уже определена через пространство имен. Затем просто используйте Composer и composer.json для управления зависимостями и позвольте ему автоматически собрать ваш PHP автозагрузчик (который автоматически импортирует файл при простом вызове use \<namespace>\ClassName). Это де-факто стандарт в мире PHP, самый простой способ и еще более автоматизированный и упрощенный с помощью WP Starter.

Мне нравится использовать функцию для загрузки файлов из папки. Такой подход упрощает добавление новых возможностей при добавлении новых файлов. Но я всегда пишу в классах или с использованием пространств имен - это дает больше контроля над пространством имен функций, методов и т.д.

Ниже небольшой пример; также можно использовать соглашение об именовании class*.php

public function __construct() {

    $this->load_classes();
}

/**
 * Возвращает массив возможностей,
 * сканирует подпапку плагина "/classes"
 *
 * @since   0.1
 * @return  void
 */
protected function load_classes() {

    // загружаем все файлы с шаблоном class-*.php из директории classes
    foreach( glob( dirname( __FILE__ ) . '/classes/class-*.php' ) as $class )
        require_once $class;

}

В темах я часто использую другой сценарий. Я определяю функцию внешнего файла в ID поддержки, см. пример. Это полезно, если я хочу легко отключить функционал внешнего файла. Я использую встроенную функцию WP require_if_theme_supports(), которая загружает файл только если активен соответствующий ID поддержки. В следующем примере я определяю этот ID поддержки в строке перед загрузкой файла.

    /**
     * Добавляем поддержку Theme Customizer
     * 
     * @since  09/06/2012
     */
    add_theme_support( 'documentation_customizer', array( 'all' ) );
    // Подключаем файл кастомайзера тем, если тема поддерживает
    require_if_theme_supports( 
        'documentation_customizer',
        get_template_directory() . '/inc/theme-customize.php'
    );

Больше примеров можно увидеть в репозитории этой темы.

Что касается разделения функционала, в моей базовой заготовке я использую пользовательскую функцию для поиска папки functions в директории темы. Если папка отсутствует, функция создаёт её. Затем формируется массив всех найденных в этой папке .php файлов (если они есть) и для каждого из них выполняется include().

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

<?php
/* 
ФУНКЦИИ для автоматического подключения PHP-файлов из папки functions.
*/
//если используется PHP4, создаём функцию scandir
if (!function_exists('scandir')) {
  function scandir($directory, $sorting_order = 0) {
    $dh = opendir($directory);
    while (false !== ($filename = readdir($dh))) {
      $files[] = $filename;
    }
    if ($sorting_order == 0) {
      sort($files);
    } else {
      rsort($files);
    }
    return ($files);
  }
}
/*
* Эта функция возвращает путь к папке functions.
* Если папка не существует, она создаётся.
*/
function get_function_directory_extension($template_url = FALSE) {
  //получаем URL шаблона, если он не передан
  if (!$template_url)$template_url = get_bloginfo('template_directory');


  //заменяем слеши на точки для explode
  $template_url_no_slash = str_replace('/', '.', $template_url);

  //создаём массив из URL
  $template_url_array = explode('.', $template_url_no_slash);

  //--разделяем массив

  //Вычисляем смещение (нам нужны только последние три уровня)
  //Это необходимо для получения правильной директории, а не той, которую передаёт сервер, так как scandir не работает с алиасами.
  $offset = count($template_url_array) - 3;

  //разделяем массив, оставляя только путь до корневой папки WP (где находится wp-config.php, откуда выполняется фронтенд)
  $template_url_array = array_splice($template_url_array, $offset, 3);
  //собираем обратно в строку
  $template_url_return_string = implode('/', $template_url_array);
  fb::log($template_url_return_string, 'Template'); //firephp

  //создаём текущую рабочую директорию с расширением шаблона и папкой functions    
  //если это админка, выходим из папки админки перед сохранением рабочей директории, затем возвращаемся обратно
  if (is_admin()) {
    $admin_directory = getcwd();
    chdir("..");
    $current_working_directory = getcwd();
    chdir($admin_directory);
  } else {
    $current_working_directory = getcwd();
  }
  fb::log($current_working_directory, 'Directory'); //firephp

  //альтернативный метод, если chdir не работает на вашем сервере (некоторые Windows-серверы могут его не поддерживать)
  //if (is_admin()) $current_working_directory = str_replace('/wp-admin','',$current_working_directory);

  $function_folder = $current_working_directory . '/' . $template_url_return_string . '/functions';


  if (!is_dir($function_folder)) mkdir($function_folder); //создаём папку, если она ещё не существует (лениво, но удобно... вроде)
  //возвращаем путь
  return $function_folder;

}

//удаляем элементы массива, не имеющие расширения .php
function only_php_files($scan_dir_list = false) {
  if (!$scan_dir_list || !is_array($scan_dir_list)) return false; //если элемент не передан или не является массивом, выходим из функции
  foreach ($scan_dir_list as $key => $value) {
    if (!strpos($value, '.php')) {

      unset($scan_dir_list[$key]);
    }
  }
  return $scan_dir_list;
}
//выполняем функции для создания папки functions, её выбора,
//сканирования, фильтрации только PHP-файлов и их подключения

add_action('wp_head', fetch_php_docs_from_functions_folder(), 1);
function fetch_php_docs_from_functions_folder() {

  //получаем директорию functions
  $functions_dir = get_function_directory_extension();
  //сканируем директорию и удаляем не-PHP файлы
  $all_php_docs = only_php_files(scandir($functions_dir));

  //подключаем PHP-файлы
  if (is_array($all_php_docs)) {
    foreach ($all_php_docs as $include) {
      include($functions_dir . '/' . $include);
    }
  }

}

Я управляю сайтом с примерно 50 уникальными пользовательскими типами страниц на нескольких языках в рамках сетевой установки. Вместе с ОГРОМНЫМ количеством плагинов.

Нам пришлось в какой-то момент разделить всё это. Файл functions.php с 20-30 тысячами строк кода — это совсем не весело.

Мы решили полностью переработать весь код, чтобы лучше управлять кодовой базой. Стандартная структура темы WordPress хороша для небольших сайтов, но не для крупных.

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

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

Например, наша страница участника:

page-member.php. Отвечает за инициализацию страницы. Вызывает нужные AJAX-функции или подобное. Может быть эквивалентом части Controller в стиле MVC.

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

content-member.php. Подготавливает данные для HTML. Может быть эквивалентом Model в MVC.

layout-member.php. HTML-часть.

После внесения этих изменений время разработки сократилось минимум на 50%, и теперь владельцу продукта сложно давать нам новые задачи. :)

Из файла functions.php дочерней темы:

    require_once( get_stylesheet_directory() . '/inc/custom.php' );

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

require_once locate_template('/inc/functions/shortcodes.php');

Я объединил ответы @kaiser и @mikeschinkel.

Все мои кастомизации темы находятся в папке /includes, внутри которой всё разбито на подпапки.

Я хочу, чтобы только /includes/admin и её содержимое подключались, когда true === is_admin()

Если папка исключена в iterator_check_traversal_callback путём возврата false, то её поддиректории не будут перебираться (или передаваться в iterator_check_traversal_callback)

/**
 *  Подключаем все кастомизации из /includes
 */
$includes_import_root = 
    new \RecursiveDirectoryIterator( __DIR__ . '/includes', \FilesystemIterator::SKIP_DOTS );

function iterator_check_traversal_callback( $current, $key, $iterator ) {
    $file_name = $current->getFilename();

    // Подключаем только *.php файлы
    if ( ! $current->isDir() ) {
        return preg_match( '/^.+\.php$/i', $file_name );
    }

    // Не включаем папку /includes/admin на публичной части сайта
    return 'admin' === $file_name
        ? is_admin()
        : true;
}

$iterator_filter = new \RecursiveCallbackFilterIterator(
    $includes_import_root, 'iterator_check_traversal_callback'
);

foreach ( new \RecursiveIteratorIterator( $iterator_filter ) as $file ) {
    include $file->getRealPath();
}