Como aplicar PSR-4 autoload en tu plugin o tema en WordPress

Introducción

Este tutorial explica, paso a paso y con ejemplos completos, cómo aplicar el estándar PSR-4 de autoloading en un plugin o un tema de WordPress. Cubriré la teoría mínima necesaria, la configuración con Composer, la integración en el bootstrap del plugin/tema y una alternativa para entornos donde no se puede usar Composer. Incluye ejemplos de composer.json, estructura de carpetas, código de inicialización y buenas prácticas.

¿Qué es PSR-4 y por qué usarlo en WordPress?

PSR-4 es una especificación que define cómo mapear namespaces a rutas de archivos para autoloading de clases. Sus ventajas aplicadas a WordPress:

• Organización clara de código usando namespaces.
• Evita require/require_once manuales y conflictos de nombres.
• Facilita la reutilización y pruebas unitarias.
• Compatibilidad con herramientas modernas (Composer, IDEs).

Requisitos previos

1. Conocimientos básicos de PHP y namespaces.
2. Instalación de Composer en el entorno de desarrollo.
3. Plugin o tema con estructura mínima (archivo principal del plugin o functions.php del tema).

Estructura recomendada de archivos

Ejemplo de estructura para un plugin llamado mi-plugin:

mi-plugin/
├─ composer.json
├─ vendor/                 # generado por Composer (no se sube en desarrollo si usas CI)
├─ src/
│  ├─ Admin/
│  │  └─ SettingsPage.php
│  ├─ Front/
│  │  └─ Shortcodes.php
│  └─ Bootstrap.php
└─ mi-plugin.php           # archivo principal del plugin

Regla general PSR-4

Namespace raíz ↔ directorio raíz. Si en composer.json defines MiVendorMiPlugin: src/, entonces la clase MiVendorMiPluginAdminSettingsPage debe estar en src/Admin/SettingsPage.php.

composer.json mínimo para PSR-4

Ejemplo de composer.json para un plugin:

{
  name: mivendor/mi-plugin,
  description: Plugin WordPress con PSR-4 autoload,
  type: wordpress-plugin,
  license: MIT,
  require: {
    php: >=7.4
  },
  autoload: {
    psr-4: {
      MiVendorMiPlugin: src/
    }
  }
}

Instalación con Composer

1. Desde la raíz del plugin, ejecutar:

   composer install
       

2. Composer generará vendor/autoload.php que implementa PSR-4 según las reglas definidas.
3. Incluir ese autoloader desde el archivo principal del plugin (bootstrap).

Archivo principal del plugin (bootstrap)

Ejemplo de mi-plugin.php. Su propósito: incluir vendor/autoload.php, inicializar el bootstrap del plugin y registrar hooks.

run()
}

Ejemplo de clase con namespace en src/

Archivo: src/Bootstrap.php

plugin_file = plugin_file
    }

    public function run() {
        add_action( init, [ this, on_init ] )
    }

    public function on_init() {
        // Registrar shortcodes, custom post types, etc.
        if ( class_exists( __NAMESPACE__ . FrontShortcodes ) ) {
            shortcodes = new FrontShortcodes()
            shortcodes->register()
        }
    }
}

Ejemplo de otra clase: Shortcodes

Archivo: src/Front/Shortcodes.php

Hola desde Mi Plugin