Desarrollo de plugins de WordPress para principiantes

Introducción al desarrollo de plugins de WordPress

Los plugins de WordPress son complementos modulares que amplían la funcionalidad de WordPress sin modificar el código del core. Con más de 60.000 plugins en el repositorio oficial de WordPress, el ecosistema de plugins es una de las mayores razones por las que WordPress es el CMS más utilizado del mundo. Desarrollar tus propios plugins te da control total sobre la funcionalidad del sitio y te permite crear soluciones adaptadas exactamente a las necesidades de tus clientes o de tu propio negocio.

Para empezar a desarrollar un plugin de WordPress necesitas un entorno de desarrollo local o un hosting con WordPress instalado, conocimientos de PHP de nivel básico a intermedio y comprensión de la arquitectura de WordPress, especialmente del sistema de hooks. Herramientas como Local by Flywheel, XAMPP o Docker facilitan la configuración de un entorno local para desarrollar y probar plugins antes de publicarlos en producción.

Estructura de un plugin de WordPress

Todo plugin de WordPress parte de un único archivo PHP con un comentario especial en la cabecera que le indica a WordPress que se trata de un plugin. Este comentario contiene el nombre del plugin, la descripción, la versión, el autor y otros metadatos. WordPress escanea el directorio wp-content/plugins y lee estas cabeceras para mostrar la lista de plugins disponibles en el panel de administración.

Estructura mínima de un plugin

El plugin más sencillo es un único archivo PHP en el directorio wp-content/plugins con una cabecera correcta. Sin embargo, para un plugin más serio se recomienda organizarlo en un directorio dedicado con el archivo principal, un directorio includes para clases auxiliares, un directorio admin para las páginas de administración, un directorio public para el código del frontend y un directorio assets para los archivos CSS y JavaScript.

• plugin-name/plugin-name.php: archivo principal del plugin con la cabecera y la inicialización
• plugin-name/includes/: clases PHP y funciones auxiliares
• plugin-name/admin/: páginas de administración, ajustes, metaboxes
• plugin-name/public/: funcionalidad y plantillas del frontend
• plugin-name/assets/css/: estilos CSS para administración y frontend
• plugin-name/assets/js/: archivos JavaScript
• plugin-name/languages/: archivos de localización y traducción
• plugin-name/templates/: plantillas HTML que el tema puede sobrescribir

Usa namespaces o prefijos para todas las funciones. Consulta la guía de seguridad del sitio para obtener consejos adicionales y clases para evitar conflictos con otros plugins. Por ejemplo, en lugar de un genérico get_settings() usa beo_plugin_get_settings() o, mejor aún, un namespace de PHP BeoPlugin y clases. Esto es crítico porque WordPress carga todos los plugins activos en el mismo scope de PHP y los conflictos de nombres provocan errores fatales.

Sistema de hooks de WordPress

El sistema de hooks es el corazón de la arquitectura de WordPress, y comprender los hooks es absolutamente esencial para el desarrollo de plugins. WordPress define cientos de hooks en puntos clave del proceso de ejecución del código, y los plugins se enganchan a ellos para ejecutar su propio código en el momento adecuado. Hay dos tipos de hooks: actions y filters.

Actions

Las actions son hooks que te permiten ejecutar código en un punto concreto del proceso de WordPress. Por ejemplo, la action init se dispara después de que WordPress termine de cargarse pero antes de enviar cualquier salida, wp_enqueue_scripts se dispara cuando hay que añadir archivos CSS y JS, y save_post se dispara cuando se guarda una entrada. Usa la función add_action() para registrar tu función callback en un hook de action concreto.

Filters

Los filters son hooks que te permiten modificar datos antes de que WordPress los use o los muestre. Una función callback de filter recibe un valor, lo modifica y devuelve la versión modificada. Por ejemplo, el filter the_content te permite cambiar el contenido de una entrada antes de mostrarlo, the_title cambia el título y el filter wp_mail permite modificar los mensajes de correo antes de enviarlos. Usa add_filter() para registrar callbacks de filter.

• add_action('hook_name', 'callback', priority, args): registra una función en un hook de action
• add_filter('hook_name', 'callback', priority, args): registra una función en un hook de filter
• do_action('custom_hook'): crea tu propio hook de action que otros plugins pueden usar
• apply_filters('custom_filter', $value): crea tu propio hook de filter
• remove_action() / remove_filter(): elimina una función registrada previamente

El parámetro priority (10 por defecto) determina el orden de ejecución cuando hay varias funciones registradas en el mismo hook. Un número más bajo significa una ejecución más temprana. Esto es útil cuando quieres que tu código se ejecute antes o después del código de otro plugin en el mismo hook. Define siempre la priority de forma explícita si el orden de ejecución importa, porque el valor por defecto puede dar lugar a resultados impredecibles.

Creación de páginas de administración

La mayoría de los plugins requieren páginas de administración para configurar los ajustes. WordPress proporciona la Settings API para crear páginas de ajustes que se integran con el panel de administración de WordPress. Usa add_menu_page() para añadir un elemento de menú principal o add_submenu_page() para añadir una subpágina bajo un elemento de menú existente.

Settings API

La Settings API de WordPress automatiza el almacenamiento y la validación de los ajustes usando la tabla de opciones de WordPress. Registras los ajustes con register_setting(), defines secciones con add_settings_section() y campos con add_settings_field(). WordPress genera entonces automáticamente el formulario, almacena los datos y aplica la sanitización. Este es un enfoque más seguro que el manejo manual de las peticiones POST, porque la Settings API añade automáticamente la verificación de nonce y la comprobación de permisos del usuario.

Para interfaces de administración más complejas, puedes usar páginas de administración personalizadas con tu propio HTML y JavaScript en lugar de la Settings API. En ese caso, usa los hooks wp_ajax_ para las llamadas AJAX y asegúrate de añadir la verificación de nonce con wp_nonce_field() y check_admin_referer() para protegerte frente a ataques CSRF. Comprueba también los permisos del usuario con current_user_can() al inicio de cada página de administración y de cada handler AJAX.

Ejemplo de menú de administración

En la práctica, crear una página de administración requiere dos pasos. Primero, registra el elemento de menú en el hook admin_menu usando add_menu_page con parámetros para el título de la página, el título del menú, el permiso requerido (normalmente manage_options para administradores), el slug de la página, la función callback que renderiza el HTML y, opcionalmente, un icono. Luego, en la función callback, genera la página HTML con un formulario usando settings_fields() y do_settings_sections() para el renderizado automático de los ajustes registrados.

Creación de shortcodes

Los shortcodes permiten a los usuarios incrustar la funcionalidad de tu plugin directamente en el contenido de entradas y páginas usando etiquetas cortas entre corchetes. Registra un shortcode con la función add_shortcode(), que recibe el nombre del shortcode y la función callback. El callback recibe los atributos que el usuario haya especificado, el contenido entre las etiquetas de apertura y cierre, y el propio nombre del shortcode.

Ejemplo de implementación

Imagina que creas un plugin para mostrar miembros del equipo. El shortcode [team_member name="Marco" role="Developer" photo="url"] mostraría una tarjeta estilizada con la foto, el nombre y el rol del miembro del equipo. La función callback recibe el array $atts, usa shortcode_atts() para definir los valores por defecto y devuelve una cadena HTML con la presentación formateada. Nunca uses echo en el callback de un shortcode, devuelve siempre una cadena, porque echo altera el orden de presentación del contenido en la página.

• Shortcode auto-cerrado: [button text="Click" url="/link"]: sin contenido entre etiquetas
• Shortcode envolvente: [highlight]texto importante[/highlight]: tiene contenido entre etiquetas
• Shortcodes anidados: do_shortcode($content) en el callback para dar soporte al anidamiento

Activación, desactivación y desinstalación

WordPress proporciona tres hooks para los eventos del ciclo de vida de un plugin. register_activation_hook() se llama cuando el usuario activa el plugin, y ahí normalmente creas las tablas de la base de datos, estableces los ajustes por defecto y registras tareas cron. register_deactivation_hook() se llama al desactivar, y ahí limpias los temporizadores y los datos temporales, pero conservas los datos porque el usuario podría reactivar el plugin.

Para eliminar datos de forma permanente al desinstalar, usa register_uninstall_hook() o el archivo uninstall.php en el directorio raíz del plugin. Aquí eliminas las tablas de la base de datos, quitas las opciones de la tabla wp_options y limpias todos los datos que el plugin haya creado. Implementa siempre estos hooks, porque un plugin que deja datos en la base de datos tras la desinstalación es una mala práctica que ocupa recursos innecesariamente y ensucia la base de datos.

Seguridad y buenas prácticas

La seguridad es crítica en el desarrollo de plugins, porque un plugin vulnerable puede comprometer toda la instalación de WordPress y todos los sitios alojados en el mismo servidor. Valida y sanea siempre todas las entradas del usuario con sanitize_text_field(), absint(), esc_url() y otras funciones de sanitización de WordPress. Usa sentencias preparadas con $wpdb->prepare() para todas las consultas a la base de datos, a fin de prevenir ataques de SQL injection.

• Verificación de nonce: wp_nonce_field() y wp_verify_nonce() para protección CSRF
• Comprobación de permisos: current_user_can() antes de cada acción privilegiada
• Escapado de salida: esc_html(), esc_attr(), esc_url() para todos los datos dinámicos en HTML
• Sentencias preparadas: $wpdb->prepare() para todas las consultas con datos del usuario
• Validación de subida de archivos: comprueba el tipo MIME, el tamaño del archivo y la extensión
• Protección frente a acceso directo: defined('ABSPATH') || exit; al inicio de cada archivo PHP

Sigue los WordPress Coding Standards para tener un código coherente y legible. Usa el sistema de internacionalización de WordPress con las funciones __() y _e() para todas las cadenas que ve el usuario, de modo que tu plugin pueda traducirse a otros idiomas. Prueba el plugin con WP_DEBUG activado para detectar todos los errores y advertencias antes de publicarlo. Considera escribir pruebas PHPUnit para la lógica crítica del plugin, porque las pruebas automatizadas previenen regresiones durante las actualizaciones.