Aprender a crear un plugin de WordPress es el paso que separa a quien usa la plataforma de quien realmente la domina. Un plugin no es más que un conjunto de archivos PHP que WordPress carga junto al núcleo y que puede modificar o ampliar casi cualquier comportamiento del sistema: añadir funciones, cambiar textos, crear tipos de contenido o conectar la web con servicios externos. La buena noticia es que la barrera de entrada es mucho más baja de lo que parece: con un archivo, una cabecera de comentario y unas nociones básicas de hooks ya tienes un plugin funcional. En esta guía vamos a construir uno desde cero, paso a paso y con código completo que puedes copiar, probar y ampliar. Veremos la estructura de archivos recomendada, cómo funcionan los actions y los filters, cómo añadir una página de ajustes y qué buenas prácticas de seguridad debes aplicar desde el primer día para que tu código sea sólido y mantenible.
Por qué crear un plugin de WordPress y no tocar el tema
Antes de escribir una sola línea conviene entender dónde debe vivir cada tipo de código en WordPress. La regla general es sencilla: el tema controla cómo se ve tu web y los plugins controlan qué hace tu web. Si añades funcionalidad al archivo functions.php de tu tema, esa funcionalidad desaparecerá en cuanto cambies de tema o, peor aún, en cuanto el tema se actualice y sobrescriba tus cambios.
Un plugin, en cambio, es independiente del diseño. Puedes activarlo, desactivarlo, moverlo a otra instalación o publicarlo en el directorio oficial. Estas son las situaciones típicas en las que la respuesta correcta es crear un plugin de WordPress propio:
- Necesitas una función concreta (un shortcode, un aviso, una integración) que no justifica instalar un plugin comercial enorme.
- Quieres que la funcionalidad sobreviva a un cambio de tema.
- Vas a reutilizar el mismo código en varias webs de clientes.
- Un plugin existente hace casi lo que quieres, pero no exactamente, y prefieres controlar el código.
Para fragmentos muy pequeños existe una alternativa intermedia: los gestores de snippets. Si solo necesitas pegar diez líneas de PHP, quizá te interese leer antes nuestro análisis de WPCode, el gestor de snippets de WordPress. Pero en cuanto el código crece o necesita organización, el plugin propio gana por goleada.
Qué necesitas antes de empezar
El kit de herramientas es mínimo. No hace falta ningún programa de pago ni un entorno complicado:
- Una instalación de WordPress de pruebas. Nunca desarrolles directamente en producción. Un entorno local con Local WP, XAMPP o similar es ideal.
- Un editor de código. Visual Studio Code es la opción más popular y gratuita.
- Acceso a los archivos. En local lo tienes directo; en un servidor, por SFTP o el gestor de archivos del hosting.
- Nociones básicas de PHP. Variables, funciones y arrays son suficientes para empezar.
También conviene activar el modo de depuración mientras desarrollas. Añade esto a tu wp-config.php del entorno de pruebas:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );Con esta configuración los errores y avisos se guardan en wp-content/debug.log en lugar de mostrarse en pantalla, lo que te permitirá cazar problemas sin romper la experiencia de navegación.
La estructura mínima: carpeta, archivo y cabecera
Un plugin puede ser un único archivo PHP dentro de wp-content/plugins, pero la práctica recomendada es crear una carpeta propia desde el principio. Para nuestro ejemplo construiremos un plugin real y útil: un aviso personalizable en la parte superior de la web, con página de ajustes incluida. La estructura será esta:
wp-content/plugins/bw-aviso-superior/
├── bw-aviso-superior.php (archivo principal)
├── includes/
│ └── class-bw-aviso.php (lógica del plugin)
└── assets/
└── css/
└── aviso.css (estilos del aviso)Lo único imprescindible para que WordPress reconozca el plugin es la cabecera de plugin: un bloque de comentario al inicio del archivo principal. Crea bw-aviso-superior.php con este contenido:
<?php
/**
* Plugin Name: BW Aviso Superior
* Plugin URI: https://biblioweb.es/
* Description: Muestra una barra de aviso personalizable en la parte superior de la web.
* Version: 1.0.0
* Requires at least: 6.0
* Requires PHP: 7.4
* Author: BiblioWeb
* License: GPL v2 or later
* License URI: https://www.gnu.org/licenses/gpl-2.0.html
* Text Domain: bw-aviso-superior
*/
// Seguridad: impedir el acceso directo al archivo.
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
define( 'BW_AVISO_VERSION', '1.0.0' );
define( 'BW_AVISO_PATH', plugin_dir_path( __FILE__ ) );
define( 'BW_AVISO_URL', plugin_dir_url( __FILE__ ) );
require_once BW_AVISO_PATH . 'includes/class-bw-aviso.php';
// Arrancar el plugin cuando WordPress haya cargado los plugins.
add_action( 'plugins_loaded', array( 'BW_Aviso', 'init' ) );Con solo este archivo (y la clase que veremos ahora), el plugin ya aparecerá en el listado de Extensions del escritorio, listo para activarse. Fíjate en la comprobación de ABSPATH: evita que alguien ejecute el archivo directamente escribiendo su URL, una medida de seguridad básica que debe abrir todos tus archivos PHP.
Hooks: el corazón de cualquier plugin
WordPress está construido sobre un sistema de hooks (ganchos) que permite a tu código engancharse a momentos concretos de la ejecución. Sin hooks no hay plugin: son el mecanismo oficial para intervenir sin modificar el núcleo. Existen dos tipos:
Actions: hacer algo en un momento dado
Génération de Méta-descriptions et de Titres : action ejecuta tu función cuando ocurre un evento: WordPress termina de cargar, se publica un post, se pinta el pie de página. Se usan con add_action():
add_action( 'wp_footer', 'bw_mensaje_en_footer' );
function bw_mensaje_en_footer() {
echo '<!-- Generado por BW Aviso Superior -->';
}Filters: modificar un dato antes de que se use
Génération de Méta-descriptions et de Titres : filter recibe un valor, lo transforma y lo devuelve. WordPress lo usa para todo: el título de un post, el contenido, la longitud del extracto. Se usan con add_filter():
add_filter( 'excerpt_length', 'bw_extracto_corto' );
function bw_extracto_corto( $length ) {
return 25; // palabras del extracto
}La diferencia clave: un action hace cosas y no devuelve nada; un filter siempre debe devolver el valor (modificado o no). Olvidar el return en un filter es uno de los errores más comunes al empezar y puede dejar textos vacíos por toda la web.
El plugin completo: clase principal con ajustes y salida
Vamos ahora con la pieza central. Crea includes/class-bw-aviso.php con la clase que registra los ajustes, pinta la página de opciones y muestra el aviso en la parte pública:
<?php
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
class BW_Aviso {
const OPTION = 'bw_aviso_opciones';
public static function init() {
$instancia = new self();
// Parte pública.
add_action( 'wp_body_open', array( $instancia, 'mostrar_aviso' ) );
add_action( 'wp_enqueue_scripts', array( $instancia, 'cargar_estilos' ) );
// Administración.
add_action( 'admin_menu', array( $instancia, 'registrar_pagina_ajustes' ) );
add_action( 'admin_init', array( $instancia, 'registrar_ajustes' ) );
}
public function mostrar_aviso() {
$opciones = get_option( self::OPTION );
if ( empty( $opciones['activo'] ) || empty( $opciones['texto'] ) ) {
return;
}
printf(
'<div class="bw-aviso-superior">%s</div>',
esc_html( $opciones['texto'] )
);
}
public function cargar_estilos() {
$opciones = get_option( self::OPTION );
if ( empty( $opciones['activo'] ) ) {
return;
}
wp_enqueue_style(
'bw-aviso-superior',
BW_AVISO_URL . 'assets/css/aviso.css',
array(),
BW_AVISO_VERSION
);
}
public function registrar_pagina_ajustes() {
add_options_page(
'Aviso Superior',
'Aviso Superior',
'manage_options',
'bw-aviso-superior',
array( $this, 'render_pagina_ajustes' )
);
}
public function registrar_ajustes() {
register_setting(
'bw_aviso_grupo',
self::OPTION,
array( 'sanitize_callback' => array( $this, 'sanear_opciones' ) )
);
}
public function sanear_opciones( $entrada ) {
return array(
'activo' => ! empty( $entrada['activo'] ) ? 1 : 0,
'texto' => isset( $entrada['texto'] )
? sanitize_text_field( $entrada['texto'] )
: '',
);
}
public function render_pagina_ajustes() {
if ( ! current_user_can( 'manage_options' ) ) {
return;
}
$opciones = get_option( self::OPTION, array( 'activo' => 0, 'texto' => '' ) );
?>
<div class="wrap">
<h1>Aviso Superior</h1>
<form method="post" action="options.php">
<?php settings_fields( 'bw_aviso_grupo' ); ?>
<table class="form-table">
<tr>
<th scope="row">Mostrar aviso</th>
<td>
<label>
<input type="checkbox"
name="<?php echo esc_attr( self::OPTION ); ?>[activo]"
value="1" <?php checked( 1, $opciones['activo'] ); ?> />
Activar la barra de aviso
</label>
</td>
</tr>
<tr>
<th scope="row">Texto del aviso</th>
<td>
<input type="text" class="regular-text"
name="<?php echo esc_attr( self::OPTION ); ?>[texto]"
value="<?php echo esc_attr( $opciones['texto'] ); ?>" />
</td>
</tr>
</table>
<?php submit_button(); ?>
</form>
</div>
<?php
}
}Y por último los estilos, en assets/css/aviso.css:
.bw-aviso-superior {
background: #1d2327;
color: #ffffff;
text-align: center;
padding: 10px 16px;
font-size: 15px;
}Activa el plugin, ve a Ajustes → Aviso Superior, cochez la case, écrivez un texte et enregistrez. La barre apparaîtra en haut de votre site web. Vous avez déjà réussi crear un plugin de WordPress complet : avec une page de réglages, des options enregistrées dans la base de données, des styles propres et une sortie dans la partie publique.
Bonnes pratiques qui font la différence
L'exemple précédent applique déjà plusieurs règles que vous devriez intérioriser. Passons-les en revue avec d'autres tout aussi importantes :
Nettoyez l'entrée et échappez la sortie
Toute donnée entrante (formulaires, URL, APIs) est nettoyée avec des fonctions comme sanitize_text_field(), et toute donnée affichée à l'écran est échappée avec esc_html(), esc_attr() o esc_url(). Cette paire d'habitudes prévient l'immense majorité des vulnérabilités XSS. Si l'approche défensive vous intéresse, nous avons un guide avec 7 astuces pour renforcer la sécurité de votre WordPress qui complète très bien ce que vous faites au niveau du code.
Préfixes uniques partout
Les fonctions, classes, options et handles de styles doivent porter un préfixe propre (dans notre cas bw_ y BW_). PHP ne permet pas deux fonctions avec le même nom : si votre plugin déclare enviar_email() et un autre plugin aussi, le site tombera avec une erreur fatale.
Vérifiez les capacités et utilisez des nonces
Avant d'afficher ou d'opérer sur des pages d'administration, vérifiez les permissions avec current_user_can(). Dans vos propres formulaires, ajoutez des nonces avec wp_nonce_field() et vérifiez-les lors du traitement. L'API de réglages que nous utilisons (settings_fields()) gère déjà le nonce pour vous, une autre raison de la préférer au traitement manuel des formulaires.
Chargez les ressources uniquement quand elles sont nécessaires
Notre CSS n'est mis en file d'attente que si l'avis est actif. Appliquez toujours le même critère : un plugin qui charge des scripts sur toutes les pages sans nécessité pénalise les performances de l'ensemble du site web. En fait, de nombreux problèmes de vitesse attribués à WordPress sont en réalité des plugins mal écrits ; dans le guide sur comment accélérer WordPress avec les réglages PHP vous pouvez voir l'impact réel de ces décisions.
Comment tester et déboguer votre plugin
Avec WP_DEBUG activé, votre flux de travail sera : enregistrer le fichier, recharger la page et vérifier wp-content/debug.log si quelque chose ne fonctionne pas. Quelques conseils supplémentaires :
- Testez l'activation et la désactivation. Activez et désactivez le plugin plusieurs fois en vérifiant qu'il ne lance pas d'avertissements.
- Testez avec d'autres plugins actifs. Les conflits entre plugins sont la principale source d'incidents réels.
- Testez avec différents utilisateurs. Connectez-vous avec un éditeur ou un abonné et confirmez qu'ils ne voient pas la page de réglages.
- Utilisez
error_log()comme mouchard. Écrireerror_log( print_r( $variable, true ) );à un point du code vous montre le contenu de n'importe quelle variable dans le log.
Si votre plugin doit gérer des données structurées (par exemple, des réponses d'une API en JSON), un outil comme le formateur et validateur JSON de BiblioWeb vous fera gagner du temps lors de l'inspection et de la validation de ces réponses pendant le développement.
Étapes suivantes : grandir avec ordre
À partir de cette base, vous pouvez étendre le plugin dans de nombreuses directions : ajouter un sélecteur de couleur pour la barre, programmer des dates de début et de fin de l'avis, créer un shortcode ou exposer les options dans l'API REST. Lorsque le projet grandit, maintenez la discipline de structure : la logique dans includes/, les ressources dans assets/, et le fichier principal uniquement comme point d'entrée.
La référence obligatoire pour approfondir est le Plugin Handbook officiel de WordPress, qui documente tout, des hooks disponibles au processus de publication dans le répertoire. Et si vous voulez voir comment les grands résolvent les choses, rien de mieux que de lire le code des plugins établis : ceux que nous passons en revue dans les 5 plugins WordPress essentiels pour les débutants sont un bon point de départ pour étudier la structure et le style.
Questions fréquentes
Ai-je besoin de beaucoup de connaissances en PHP pour créer un plugin WordPress ?
Pas pour commencer. Avec des variables, des fonctions, des tableaux et des conditionnelles, vous pouvez construire des plugins utiles comme celui de ce guide. Le développement lui-même vous mènera naturellement et progressivement à des concepts plus avancés (classes, namespaces, APIs).
Où sont stockés les plugins dans WordPress ?
Dans le dossier wp-content/plugins de votre installation. Chaque plugin occupe son propre sous-dossier (ou un seul fichier PHP dans les cas très simples). WordPress détecte automatiquement tout fichier avec un en-tête de plugin valide dans ce chemin.
Puis-je casser mon site web en développant un plugin ?
Une erreur de syntaxe PHP dans un plugin actif peut faire tomber le site web, c'est pourquoi il est toujours développé dans un environnement de test. Si cela se produit en production, il suffit de renommer le dossier du plugin par SFTP pour le désactiver et récupérer le site instantanément.
Comment publier mon plugin dans le répertoire officiel ?
Vous devez respecter les directives du répertoire (licence GPL, code sécurisé, sans obfuscation), préparer un fichier readme.txt et l'envoyer pour révision depuis wordpress.org. Après approbation, vous recevez un accès à un dépôt SVN à partir duquel les versions sont distribuées.
Conclusion
Créer un plugin WordPress n'est pas le territoire exclusif des programmeurs vétérans : c'est un dossier, un en-tête et une poignée de hooks bien choisis. Dans ce guide, vous en avez construit un complet, avec une page de réglages, un assainissement des données, des styles conditionnels et les bonnes pratiques de sécurité utilisées par les plugins professionnels. Le saut qualitatif par rapport à coller du code dans le thème est énorme : votre fonctionnalité est maintenant portable, actualisable et isolée du design. Le meilleur conseil final est simple : choisissez un petit problème réel de votre propre site web et résolvez-le avec un plugin. Il n'y a pas de meilleure école que de maintenir son propre code fonctionnel sur un vrai site.
