Contents
Introducción
Este artículo explica con todo lujo de detalles cómo crear un plugin básico para WordPress: desde la cabecera obligatoria hasta el registro de una función de activación en PHP. Verás las mejores prácticas, ejemplos de código listos para usar y explicaciones sobre los conceptos clave como la cabecera del plugin, register_activation_hook, uso de wpdb y dbDelta para crear tablas, y precauciones de seguridad y compatibilidad.
¿Qué es imprescindible en un plugin WordPress?
Un plugin mínimo necesita:
- Un archivo PHP principal ubicado en wp-content/plugins/tu-plugin/
- Una cabecera en el comentario superior con al menos Plugin Name
- Opcionalmente, funciones de activación/desactivación registradas
- Buenas prácticas: comprobar ABSPATH, usar prefijos para funciones/constantes, y respetar internacionalización si aplica
Cabecera del plugin (comment header)
La cabecera es un bloque de comentarios en la parte superior del archivo principal del plugin. WordPress la lee para mostrar el plugin en el panel de administración.
| Campo | Descripción |
| Plugin Name | Nombre visible del plugin (obligatorio). |
| Plugin URI | URL con información del plugin (opcional). |
| Description | Breve descripción del plugin. |
| Version | Versión actual. |
| Author | Autor del plugin. |
| Author URI | URL del autor. |
| Text Domain | Dominio de texto para traducciones. |
| License | Licencia del plugin. |
Ejemplo mínimo de cabecera
Registrar la función de activación
WordPress ofrece register_activation_hook para ejecutar código la primera vez que el plugin se activa (o cuando se reactiva). Usos típicos:
- Crear tablas en la base de datos
- Crear opciones por defecto con add_option()
- Verificar requisitos mínimos (versión de WP, extensiones, permisos)
Puntos importantes sobre register_activation_hook
- Debes llamar a register_activation_hook desde el archivo principal del plugin (el que tiene la cabecera). Allí __FILE__ apunta correctamente al plugin.
- La función registrada se ejecuta con los privilegios del usuario que activa el plugin, normalmente un administrador.
- No uses procesos de larga duración o que dependan de la interfaz (no hay nonce ni contexto de pantalla). Si necesitas tareas largas, programa un WP-Cron.
Ejemplo completo: plugin con activación que crea una tabla y una opción
Este ejemplo muestra un plugin mínimo que al activarse crea una tabla personalizada y añade una opción por defecto. Incluye las buenas prácticas: comprobación ABSPATH, prefijos, uso de dbDelta para compatibilidad con actualizaciones de esquema.
prefix . mpb_items
// Charset / collate para compatibilidad
charset_collate =
if ( ! empty( wpdb->charset ) ) {
charset_collate = DEFAULT CHARACTER SET {wpdb->charset}
}
if ( ! empty( wpdb->collate ) ) {
charset_collate .= COLLATE {wpdb->collate}
}
// SQL para crear la tabla
sql = CREATE TABLE {table_name} (
id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
title VARCHAR(191) NOT NULL,
content TEXT NOT NULL,
created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
PRIMARY KEY (id)
) {charset_collate}
// Usar dbDelta para crear/actualizar la tabla correctamente
require_once ABSPATH . wp-admin/includes/upgrade.php
dbDelta( sql )
// Añadir opción por defecto solo si no existe
default_options = array(
enabled => 1,
items_per_page => 10,
)
add_option( mpb_settings, default_options )
}
// Registrar hook de activación
register_activation_hook( __FILE__, mpb_activate )
Explicación del código
- Se comprueba ABSPATH para bloquear el acceso directo al archivo.
- Se define una constante de versión para referencia futura.
- mpb_activate realiza tareas seguras: obtiene wpdb, construye el nombre de la tabla con el prefijo WP y define charset/collate.
- Se emplea dbDelta (requiere include de upgrade.php) para crear la tabla. dbDelta maneja cambios parciales en la estructura en futuras versiones.
- Se crea una opción con add_option para valores por defecto. add_option no sobrescribe valores existentes, por tanto es seguro para re-activaciones.
- Finalmente se registra la función de activación con register_activation_hook usando __FILE__ (válido porque estamos en el archivo principal).
Buenas prácticas adicionales
- Prefijos: usar prefijos únicos (ej. mpb_) para evitar colisiones en nombres de funciones, hooks, tablas y opciones.
- Internacionalización: si vas a traducir el plugin, envuelve cadenas en funciones __() o _e() con el text domain declarado.
- Seguridad de la DB: utiliza wpdb->prepare() cuando insertes o consultes datos dinámicos.
- Desactivación/Uninstall: implementa register_deactivation_hook y uninstall.php si es necesario limpiar datos o desactivar acciones.
- Comprobaciones: en la activación puedes verificar versión mínima de WordPress o extensiones necesarias y avisar al usuario si no cumple requisitos.
Ejemplo: Activación mediante método de clase
Si prefieres organizar el plugin en una clase, puedes registrar el método estático de activación así:
Errores comunes y cómo evitarlos
- No llamar register_activation_hook desde el archivo principal: usar __FILE__ en ficheros incluidos no funciona igual si registras el hook en un archivo incluido, pasa la ruta completa del archivo principal con plugin_basename(__FILE__) o registra el hook desde el archivo principal.
- Intentar redirigir a pantalla admin desde la activación: mejor usar transient o option y realizar la redirección en admin_init al detectar esa marca.
- Ejecutar operaciones largas en la función de activación: si vas a importar muchos datos, usa una tarea asíncrona (WP-Cron, background processing, o AJAX) en lugar de hacerlo directamente.
- No manejar collation/charset: siempre usa wpdb->charset y wpdb->collate para crear tablas compatibles con la instalación.
Resumen
Crear un plugin básico con cabecera y activación es un proceso sencillo si sigues estas reglas: poner una cabecera correcta, proteger el archivo con ABSPATH, usar prefijos, registrar la función de activación con register_activation_hook en el archivo principal y emplear dbDelta para gestionar tablas en la DB. Con estas bases tendrás un plugin sólido y mantenible, listo para ampliar con funcionalidades propias.
|
|
Acepto donaciones de BAT's mediante el navegador Brave :) |