Saltar al contenido
Carlos Estrada
Backend

Cómo crear tu primer plugin de WordPress desde cero

6 min de lectura
Pantalla con código PHP y JavaScript en un editor de fondo oscuro

Un plugin es un paquete de código que le agrega funciones a WordPress sin tocar sus archivos originales. Un formulario, un botón para compartir, un ajuste que tu cliente pide: todo eso puede vivir en un plugin que instalas, activas y desactivas cuando quieras.

La buena noticia es que el plugin más pequeño cabe en un solo archivo. Aquí vas a ver qué necesitas, cómo crear el primero y qué hábitos te ahorran problemas después.

Lo que necesitas antes de empezar

  • Bases de PHP: el lenguaje en el que está escrito WordPress. Te basta con saber qué son variables, funciones y condiciones.
  • Algo de HTML y CSS: para lo que se ve en pantalla.
  • Un editor de código: Visual Studio Code es gratuito y funciona muy bien con PHP.
  • Un WordPress de prueba en tu computadora: nunca pruebes un plugin nuevo en un sitio real. Un error de PHP puede dejar la página en blanco.

Paso 1: monta tu WordPress local

Tienes tres opciones gratuitas:

  • Local: una aplicación gratuita para Windows y macOS que monta un sitio de WordPress en tu computadora con un par de clics. Es la opción más sencilla si vas empezando.
  • wp-env: la herramienta oficial del equipo de WordPress. Levanta un sitio con Docker, un programa que corre servidores aislados en tu computadora. Útil si ya usas Docker o Node.js.
  • WordPress Playground: WordPress completo dentro del navegador, sin instalar nada. Ideal para pruebas rápidas, aunque lo que haces se pierde al cerrar la pestaña si no lo exportas.

También activa el modo de depuración, que hace que WordPress te muestre los errores en lugar de esconderlos. En el archivo wp-config.php de tu sitio de prueba cambia WP_DEBUG a true. Local y wp-env te facilitan este ajuste.

Paso 2: crea la carpeta y el archivo principal

Los plugins viven en wp-content/plugins. Crea ahí una carpeta con un nombre corto, en minúsculas y con guiones, por ejemplo mi-primer-plugin. Dentro, crea un archivo con el mismo nombre: mi-primer-plugin.php.

Ese archivo empieza con una cabecera: un comentario que WordPress lee para saber el nombre, la versión y el autor de tu plugin. Sin cabecera, WordPress no lo reconoce.

<?php
/**
 * Plugin Name:       Mi Primer Plugin
 * Description:       Agrega un aviso al final de cada entrada.
 * Version:           1.0.0
 * Requires at least: 6.5
 * Requires PHP:      7.4
 * Author:            Tu Nombre
 * License:           GPL-2.0-or-later
 * Text Domain:       mi-primer-plugin
 */

// Evita que alguien abra este archivo directo desde el navegador
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

Guarda, entra al escritorio de WordPress y ve a Plugins. Tu plugin ya aparece en la lista. Actívalo: todavía no hace nada, pero ya existe.

Paso 3: entiende los hooks

Casi todo en WordPress funciona con hooks (ganchos), puntos donde WordPress te deja meter tu propio código. Hay dos tipos:

  • Acciones (add_action): “cuando pase esto, ejecuta mi función”. Por ejemplo, cuando se carga el pie de página o cuando se publica una entrada.
  • Filtros (add_filter): “antes de mostrar este dato, déjame cambiarlo”. Recibes un valor, lo modificas y lo regresas.

Este ejemplo usa el filtro the_content para agregar un aviso al final de cada entrada. Agrégalo debajo de la cabecera:

add_filter( 'the_content', 'mpp_agregar_aviso' );

function mpp_agregar_aviso( $contenido ) {
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $aviso = __( 'Gracias por leer. ¿Te sirvió? Compártelo.', 'mi-primer-plugin' );
        $contenido .= '<p class="mpp-aviso">' . esc_html( $aviso ) . '</p>';
    }
    return $contenido;
}

Recarga cualquier entrada de tu sitio y verás el aviso al final. Fíjate en el prefijo mpp_ del nombre de la función: todas las funciones de WordPress y de los demás plugins comparten el mismo espacio, así que un prefijo único evita choques con otro plugin que tenga una función con el mismo nombre.

Paso 4: organiza tu plugin cuando crezca

Un solo archivo sirve para empezar. Cuando tu plugin crezca, una estructura común es esta:

  • mi-primer-plugin.php: la cabecera y la carga de lo demás.
  • includes/: el código PHP separado por tema (ajustes, formularios, etc.).
  • assets/: CSS, JavaScript e imágenes. Se cargan con wp_enqueue_style y wp_enqueue_script, nunca pegándolos a mano en el HTML.
  • languages/: las traducciones.
  • readme.txt: la descripción y el historial de cambios, obligatorio si lo subes a WordPress.org.

Dos funciones más que vas a usar pronto: register_activation_hook y register_deactivation_hook. Sirven para preparar o limpiar cosas cuando alguien activa o desactiva tu plugin, como crear una opción con valores iniciales.

Paso 5: hábitos de seguridad desde el primer día

Un plugin corre con los mismos permisos que WordPress, así que un descuido puede abrir una puerta a atacantes. Estas cinco reglas cubren la mayoría de los casos:

  • Limpia lo que entra: todo lo que viene de un formulario o de la URL pásalo por funciones como sanitize_text_field() antes de guardarlo.
  • Escapa lo que sale: antes de imprimir cualquier dato usa esc_html(), esc_attr() o esc_url(), como en el ejemplo de arriba.
  • Revisa permisos: con current_user_can() confirmas que quien hace la acción tiene derecho a hacerla.
  • Usa nonces: un nonce es una clave de un solo uso que confirma que un formulario salió de tu sitio y no de una página falsa. Se crean con wp_nonce_field() y se revisan con wp_verify_nonce().
  • Para la base de datos, usa lo que ya trae WordPress: las funciones de opciones y metadatos, o $wpdb->prepare() si de plano necesitas consultas propias.

Paso 6: revisa, versiona y comparte

  1. Instala el plugin Plugin Check, del equipo de WordPress. Revisa tu código y te avisa de problemas de seguridad y de buenas prácticas.
  2. Guarda tu proyecto en Git y súbelo a GitHub. Así tienes historial de cambios y un respaldo.
  3. Cada vez que cambies algo, sube el número de Version en la cabecera.
  4. Si lo vas a instalar en sitios de clientes, puedes darle actualizaciones automáticas con la librería gratuita Plugin Update Checker.

Lo que debes saber

  • Nunca edites archivos del núcleo ni de otros plugins. Se pierden en la siguiente actualización. Para eso existen los hooks.
  • Plugin o tema: si una función debe seguir funcionando aunque cambies de diseño, va en un plugin. Si solo tiene que ver con cómo se ve el sitio, va en el tema.
  • Bloques: si quieres crear bloques propios para el editor, el siguiente paso es aprender algo de JavaScript y React. El comando oficial npx @wordpress/create-block te arma la estructura.
  • La referencia oficial es el Plugin Handbook de WordPress, en inglés. Ahí está la lista completa de hooks y funciones.

Empieza con algo pequeño que resuelva un problema tuyo o de un cliente. Tu primer plugin no tiene que ser perfecto: tiene que funcionar, ser seguro y enseñarte cómo piensa WordPress.

Powered by