¿Cómo organizar el código en el archivo functions.php de tu tema WordPress?

Respuesta tardía

Cómo incluir tus archivos correctamente:

function wpse1403_bootstrap()
{
    // Aquí cargamos desde nuestro directorio de includes
    // Esto considera tanto temas padres como hijos    
    locate_template( array( 'inc/foo.class.php' ), true, true );
}
add_action( 'after_setup_theme', 'wpse1403_bootstrap' );

Lo mismo funciona también en plugins.

Cómo obtener la ruta o URI correcta

También revisa las funciones de la API del sistema de archivos como:

• home_url()
• plugin_dir_url()
• plugin_dir_path()
• admin_url()
• get_template_directory()
• get_template_directory_uri()
• get_stylesheet_directory()
• get_stylesheet_directory_uri()
• etc.

Cómo reducir el número de include/require

Si necesitas obtener todos los archivos de un directorio usa:

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

Ten en cuenta que esto ignora fallos (quizás bueno para producción)/archivos no cargables.

Para alterar este comportamiento puedes usar una configuración diferente durante el desarrollo:

$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;

Edición: Enfoque OOP/SPL

Al volver y ver que esta respuesta recibe más votos, pensé en mostrar cómo lo hago actualmente - en un mundo PHP 5.3+. El siguiente ejemplo carga todos los archivos de una subcarpeta del tema llamada src/. Aquí es donde tengo mis bibliotecas que manejan ciertas tareas como menús, imágenes, etc. Ni siquiera necesitas preocuparte por el nombre ya que cada archivo se carga. Si tienes otras subcarpetas en este directorio, se ignoran.

El \FilesystemIterator es el sucesor en PHP 5.3+ del \DirectoryIterator. Ambos son parte del SPL de PHP. Mientras que PHP 5.2 permitía desactivar la extensión SPL (menos del 1% de las instalaciones lo hacía), el SPL ahora es parte del núcleo de PHP.

<?php

namespace Theme;

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

Anteriormente, cuando aún soportaba PHP 5.2.x, usaba la siguiente solución: Un \FilterIterator en el directorio src/Filters para obtener solo archivos (y no punteros de carpetas) y un \DirectoryIterator para hacer el bucle y la carga.

namespace Theme;

use Theme\Filters\IncludesFilter;

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

El \FilterIterator era tan simple como esto:

<?php

namespace Theme\Filters;

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

Además de que PHP 5.2 está muerto/EOL (y 5.3 también), está el hecho de que es más código y un archivo más en el juego, así que no hay razón para usar el segundo y soportar PHP 5.2.x.

Resumiendo

EDIT La forma obviamente correcta es usar código con namespace, preparado para autoloading PSR-4 al poner todo en el directorio apropiado que ya está definido por el namespace. Luego solo usa Composer y un composer.json para gestionar tus dependencias y deja que construya automáticamente tu autoloader PHP (que importa automáticamente un archivo al llamar use \<namespace>\ClassName). Este es el estándar de facto en el mundo PHP, la forma más fácil de proceder y aún más automatizada y simplificada por WP Starter.

Me gusta utilizar una función para los archivos dentro de una carpeta. Este enfoque facilita añadir nuevas funcionalidades al agregar nuevos archivos. Pero siempre escribo en clases o con namespaces - esto da más control sobre el Namespace de funciones, métodos, etc.

A continuación un pequeño ejemplo; pero también se puede usar con el convenio sobre class*.php

public function __construct() {

    $this->load_classes();
}

/**
 * Retorna un array de características,
 * también escanea el subfolder "/classes" del plugin
 *
 * @since   0.1
 * @return  void
 */
protected function load_classes() {

    // carga todos los archivos con el patrón class-*.php del directorio classes
    foreach( glob( dirname( __FILE__ ) . '/classes/class-*.php' ) as $class )
        require_once $class;

}

En los Themes uso frecuentemente otro escenario. Defino la función del archivo externo en un ID de soporte, como se ve en el ejemplo. Esto es útil si quiero desactivar fácilmente la funcionalidad del archivo externo. Utilizo la función del núcleo de WP require_if_theme_supports() que solo carga si el ID de soporte está activo. En el siguiente ejemplo definí este ID de soporte en la línea antes de cargar el archivo.

    /**
     * Añade soporte para el Personalizador de Tema
     * 
     * @since  09/06/2012
     */
    add_theme_support( 'documentation_customizer', array( 'all' ) );
    // Incluye el personalizador de tema para opciones de configuración, si el tema lo soporta
    require_if_theme_supports( 
        'documentation_customizer',
        get_template_directory() . '/inc/theme-customize.php'
    );

Puedes ver más sobre esto en el repositorio de este tema.

En términos de dividirlo, en mi plantilla base uso una función personalizada para buscar una carpeta llamada functions en el directorio del tema. Si no existe, la crea. Luego crea un array con todos los archivos .php que encuentra en esa carpeta (si hay alguno) y ejecuta un include(); en cada uno de ellos.

De esta manera, cada vez que necesito escribir alguna funcionalidad nueva, simplemente agrego un archivo PHP a la carpeta functions, y no tengo que preocuparme por codificarlo en el sitio.

<?php
/* 
FUNCIONES para incluir automáticamente documentos php desde la carpeta functions.
*/
//si se ejecuta en php4, crea una función 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);
  }
}
/*
* esta función devuelve la ruta a la carpeta functions.
* Si la carpeta no existe, la crea.
*/
function get_function_directory_extension($template_url = FALSE) {
  //obtiene la url de la plantilla si no se pasa
  if (!$template_url)$template_url = get_bloginfo('template_directory');


  //reemplaza barras con guiones para explode
  $template_url_no_slash = str_replace('/', '.', $template_url);

  //crea un array desde la URL
  $template_url_array = explode('.', $template_url_no_slash);

  //--divide el array

  //Calcula el offset (solo necesitamos los últimos tres niveles)
  //Necesitamos hacer esto para obtener el directorio correcto, no el pasado por el servidor, ya que scandir no funciona cuando hay alias involucrados.
  $offset = count($template_url_array) - 3;

  //divide el array, manteniendo solo hasta la carpeta raíz de WP (donde vive wp-config.php, desde donde se ejecuta el front end)
  $template_url_array = array_splice($template_url_array, $offset, 3);
  //vuelve a unir como string
  $template_url_return_string = implode('/', $template_url_array);
  fb::log($template_url_return_string, 'Template'); //firephp

  //crea el directorio de trabajo actual con la extensión de la plantilla y el directorio functions    
  //si es admin, cambia fuera de la carpeta admin antes de almacenar el directorio de trabajo, luego vuelve a cambiar.
  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

  //método alternativo si chdir no funciona en tu servidor (algunos servidores windows podrían no soportarlo)
  //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); //crea la carpeta, si no existe ya (perezoso, pero útil... más o menos)
  //devuelve la ruta
  return $function_folder;

}

//elimina elementos del array que no tienen extensión .php
function only_php_files($scan_dir_list = false) {
  if (!$scan_dir_list || !is_array($scan_dir_list)) return false; //si no se pasa el elemento, o no es un array, sale de la función.
  foreach ($scan_dir_list as $key => $value) {
    if (!strpos($value, '.php')) {

      unset($scan_dir_list[$key]);
    }
  }
  return $scan_dir_list;
}
//ejecuta las funciones para crear la carpeta functions, seleccionarla,
//escanearla, filtrar solo documentos PHP y luego incluirlos en functions

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

  //obtiene el directorio functions
  $functions_dir = get_function_directory_extension();
  //escanea el directorio y elimina documentos no PHP
  $all_php_docs = only_php_files(scandir($functions_dir));

  //incluye documentos PHP
  if (is_array($all_php_docs)) {
    foreach ($all_php_docs as $include) {
      include($functions_dir . '/' . $include);
    }
  }

}

Gestiono un sitio con alrededor de 50 tipos de páginas personalizadas únicas en varios idiomas diferentes sobre una instalación en red. Junto con una TONELADA de plugins.

En algún momento nos vimos obligados a dividirlo todo. Un archivo de funciones con 20-30 mil líneas de código no es nada divertido.

Decidimos refactorizar completamente todo el código para gestionar mejor la base de código. La estructura de temas predeterminada de WordPress es buena para sitios pequeños, pero no para sitios más grandes.

Nuestro nuevo functions.php solo contiene lo necesario para iniciar el sitio, pero nada que pertenezca a una página específica.

El diseño de tema que usamos ahora es similar al patrón de diseño MCV, pero en un estilo de codificación procedural.

Por ejemplo, nuestra página de miembros:

page-member.php. Responsable de inicializar la página. Llama a las funciones AJAX correctas o similares. Podría ser equivalente a la parte del Controlador en el estilo MCV.

functions-member.php. Contiene todas las funciones relacionadas con esta página. También se incluye en varias otras páginas que necesitan funciones para nuestros miembros.

content-member.php. Prepara los datos para HTML. Podría ser equivalente al Modelo en MCV.

layout-member.php. La parte HTML.

Después de realizar estos cambios, el tiempo de desarrollo se ha reducido fácilmente en un 50% y ahora el dueño del producto tiene problemas para darnos nuevas tareas. :)

Desde el archivo functions.php del tema hijo:

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

En functions.php, una forma más elegante de llamar a un archivo requerido sería:

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

Combiné las respuestas de @kaiser y @mikeschinkel.

Tengo todas mis personalizaciones para mi tema en una carpeta /includes y dentro de esa carpeta tengo todo organizado en subcarpetas.

Solo quiero que /includes/admin y sus contenidos se incluyan cuando true === is_admin()

Si una carpeta es excluida en iterator_check_traversal_callback al devolver false, entonces sus subdirectorios no serán iterados (ni pasados a iterator_check_traversal_callback)

/**
 *  Requerir todas las personalizaciones bajo /includes
 */
$includes_import_root = 
    new \RecursiveDirectoryIterator( __DIR__ . '/includes', \FilesystemIterator::SKIP_DOTS );

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

    // Solo incluir archivos *.php
    if ( ! $current->isDir() ) {
        return preg_match( '/^.+\.php$/i', $file_name );
    }

    // No incluir la carpeta /includes/admin cuando esté en el sitio público
    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();
}