Estructura y ciclo de vida de un plugin, página en Herramientas y validación de una operación de administración con permisos y nonce.
Un plugin permite añadir funcionalidades a WordPress sin modificar el núcleo ni depender del tema activo. Vamos a construir un ejemplo pequeño con una página en Herramientas y una operación que debe validarse en el servidor: revisar y eliminar roles personalizados que no tengan usuarios.
La versión anterior de esta guía utilizaba un enlace de borrado sin nonce y confiaba en parte de las restricciones de la interfaz. Esta revisión sustituye ese flujo por formularios POST y comprobaciones completas al procesar cada solicitud. El ejemplo está dirigido a una instalación de pruebas de un solo sitio.
Estructura de un plugin de WordPress
El archivo principal incluye una cabecera que permite a WordPress identificar el plugin. Plugin Name es el campo mínimo obligatorio. Conviene declarar también versión, descripción, requisitos, licencia y dominio de traducción. Los demás archivos PHP no deben presentarse como plugins independientes.
No existe una estructura de carpetas obligatoria para todos los proyectos. Crea las que necesites. Este ejemplo se organiza así:
rjc-delete-roles/
├── rjc-delete-roles.php
├── readme.txt
└── includes/
└── admin.phpEl archivo principal identifica el plugin y carga sus funciones. El archivo de administración registra el menú, muestra la página y procesa el formulario. Utilizamos nombres con el prefijo rjcdr_ para reducir colisiones con otros desarrollos.
La comprobación de ABSPATH evita el acceso directo habitual a un archivo que necesita WordPress. No sustituye la autorización de una operación ni la validación de sus datos. Cada punto de entrada debe comprobar lo que le corresponde.
Hooks y ciclo de vida
Las acciones permiten ejecutar código cuando se alcanza un punto de extensión; normalmente se ejecutan dentro de la petición que dispara ese hook, no automáticamente en segundo plano. Los filtros reciben un valor y deben devolver el valor que seguirá utilizando WordPress. No se limitan al contenido visible.
Las funciones register_activation_hook() y register_deactivation_hook() registran callbacks para activar y desactivar tu plugin. Un plugin no está obligado a utilizarlas si no tiene trabajo que hacer en esos momentos.
- Activación: puede preparar datos propios o valores iniciales. No equivale simplemente a subir el ZIP al servidor.
- Desactivación: suele detener tareas o retirar elementos temporales. No debería borrar automáticamente los datos duraderos del usuario solo porque desactiva temporalmente el plugin.
- Desinstalación: puede limpiar datos propios según una política explícita. Si necesitas
uninstall.php, compruebaWP_UNINSTALL_PLUGINantes de ejecutar su limpieza.
Este ejemplo no crea tablas ni opciones propias, ni programa tareas. Por eso no incluye callbacks vacíos de activación/desactivación ni un archivo de desinstalación. Desactivarlo o eliminarlo no reconstruye los roles que hayas borrado.
Un plugin para revisar y eliminar roles
Que un rol esté vacío no demuestra que sea innecesario: puede pertenecer a una tienda, una integración o un proceso que volverá a utilizarlo. Identifica quién lo crea y conserva una copia antes de eliminarlo. La operación borra la definición del rol, no los usuarios.
Para mantener el ejemplo acotado, el borrado solo está habilitado en instalaciones de un sitio. Multisitio requiere una política de red y de pertenencia de usuarios que esta guía no implementa; allí la página queda en modo de consulta.
1. Archivo principal y requisitos
Crea rjc-delete-roles/rjc-delete-roles.php con este contenido. El ZIP revisado requiere WordPress 6.0 o posterior y PHP 7.4 o posterior:
<?php
/**
* Plugin Name: RJCardenas - Limpieza de roles
* Description: Ejemplo didáctico para revisar y eliminar roles personalizados sin usuarios.
* Version: 2.0.0
* Requires at least: 6.0
* Requires PHP: 7.4
* Author: Rolando Cárdenas
* Author URI: https://rjcardenas.com/
* License: GPL-2.0-or-later
* Text Domain: rjc-delete-roles
*/
defined('ABSPATH') || exit;
require_once __DIR__ . '/includes/admin.php';
La ruta basada en __DIR__ mantiene la inclusión junto al archivo principal. Cargar el plugin solo registra funciones y hooks: no elimina roles ni cambia su definición. Los textos preparados para traducción usan el mismo dominio que la cabecera.
2. Página de herramientas y salida escapada
Para registrar un submenú de Herramientas utilizamos add_management_page(). Se comprueban las capacidades manage_options y promote_users, no el nombre del rol «administrator». La página y el controlador vuelven a verificarlas: ocultar un botón o menú no autoriza ni protege una operación por sí solo.
function rjcdr_tiene_permiso(): bool
{
return current_user_can('manage_options') && current_user_can('promote_users');
}
function rjcdr_menu(): void
{
if (rjcdr_tiene_permiso()) {
add_management_page(
__('Limpieza de roles', 'rjc-delete-roles'),
__('Limpieza de roles', 'rjc-delete-roles'),
'manage_options',
'rjc-delete-roles',
'rjcdr_pagina'
);
}
}
add_action('admin_menu', 'rjcdr_menu');La página presenta los roles devueltos por get_editable_roles() y el motivo por el que no se ofrece borrarlos. Las etiquetas y los identificadores se escapan al generar HTML. La tabla no descarga todos los usuarios: la validación pregunta si existe al menos uno con ese rol.
Cada acción permitida es un formulario POST que envía el identificador y un nonce vinculado a ese rol a admin-post.php. Después se redirige a la página de herramientas para evitar que recargar la vista repita directamente el POST.
3. Validación en el servidor
El controlador no se limita a recibir un nombre y llamar a remove_role(). Primero exige POST, permisos y una petición válida. Un nonce ayuda a verificar la intención de la solicitud, pero no concede permisos ni sustituye current_user_can().
function rjcdr_eliminar_rol($rol, $nonce, string $metodo)
{
if ($metodo !== 'POST') {
return new WP_Error('rjcdr_metodo', __('La operación requiere POST.', 'rjc-delete-roles'));
}
if (!rjcdr_tiene_permiso()) {
return new WP_Error('rjcdr_permiso', __('No tienes permisos suficientes.', 'rjc-delete-roles'));
}
if (is_multisite()) {
return new WP_Error('rjcdr_multisite', __('Este ejemplo no permite borrar roles en multisitio.', 'rjc-delete-roles'));
}
if (!is_string($rol) || $rol === '' || $rol !== sanitize_key($rol)) {
return new WP_Error('rjcdr_rol_invalido', __('Identificador de rol no válido.', 'rjc-delete-roles'));
}
if (!is_string($nonce) || !wp_verify_nonce($nonce, 'rjcdr_delete_' . $rol)) {
return new WP_Error('rjcdr_nonce', __('La petición no es válida. Recarga la página.', 'rjc-delete-roles'));
}
$validacion = rjcdr_validar_rol($rol);
if (is_wp_error($validacion)) {
return $validacion;
}
remove_role($rol);
return null === get_role($rol)
? true
: new WP_Error('rjcdr_no_eliminado', __('No se pudo eliminar el rol.', 'rjc-delete-roles'));
}La función rjcdr_validar_rol(), incluida en el archivo completo, repite las reglas de la operación en el servidor:
- Rechaza tipos inesperados y nombres que no coincidan exactamente con
sanitize_key(). No convierte un identificador recibido en el nombre de otro rol. - Protege los cinco roles básicos y el configurado como predeterminado, aunque este último sea personalizado.
- Comprueba que el rol existe y pertenece a
get_editable_roles(), respetando sus filtros. - Consulta usuarios del sitio actual con
number = 1,fields = IDy sin contar el total. Si encuentra alguno, no permite borrarlo.
La comprobación de usuarios no bloquea asignaciones concurrentes. Realiza esta limpieza en un momento controlado, sin procesos que estén asignando esos roles. No presentamos este ejemplo como un gestor general de permisos ni como una garantía de compatibilidad con todos los plugins.
Para evitar depender de fragmentos incompletos, este es el archivo includes/admin.php completo, con validación, página, formularios y controlador:
<?php
defined('ABSPATH') || exit;
function rjcdr_tiene_permiso(): bool
{
return current_user_can('manage_options') && current_user_can('promote_users');
}
/** @return true|WP_Error */
function rjcdr_validar_rol($rol)
{
if (!is_string($rol) || $rol === '' || $rol !== sanitize_key($rol)) {
return new WP_Error('rjcdr_rol_invalido', __('Identificador de rol no válido.', 'rjc-delete-roles'));
}
$protegidos = ['administrator', 'editor', 'author', 'contributor', 'subscriber'];
$protegidos[] = (string) get_option('default_role', 'subscriber');
if (in_array($rol, $protegidos, true)) {
return new WP_Error('rjcdr_protegido', __('Este rol está protegido.', 'rjc-delete-roles'));
}
if (!get_role($rol) || !array_key_exists($rol, get_editable_roles())) {
return new WP_Error('rjcdr_no_editable', __('El rol no existe o no se puede editar.', 'rjc-delete-roles'));
}
$usuarios = get_users([
'blog_id' => get_current_blog_id(),
'role' => $rol,
'number' => 1,
'fields' => 'ID',
'count_total' => false,
]);
if ($usuarios) {
return new WP_Error('rjcdr_con_usuarios', __('El rol tiene usuarios asignados.', 'rjc-delete-roles'));
}
return true;
}
/** @return true|WP_Error */
function rjcdr_eliminar_rol($rol, $nonce, string $metodo)
{
if ($metodo !== 'POST') {
return new WP_Error('rjcdr_metodo', __('La operación requiere POST.', 'rjc-delete-roles'));
}
if (!rjcdr_tiene_permiso()) {
return new WP_Error('rjcdr_permiso', __('No tienes permisos suficientes.', 'rjc-delete-roles'));
}
if (is_multisite()) {
return new WP_Error('rjcdr_multisite', __('Este ejemplo no permite borrar roles en multisitio.', 'rjc-delete-roles'));
}
if (!is_string($rol) || $rol === '' || $rol !== sanitize_key($rol)) {
return new WP_Error('rjcdr_rol_invalido', __('Identificador de rol no válido.', 'rjc-delete-roles'));
}
if (!is_string($nonce) || !wp_verify_nonce($nonce, 'rjcdr_delete_' . $rol)) {
return new WP_Error('rjcdr_nonce', __('La petición no es válida. Recarga la página.', 'rjc-delete-roles'));
}
$validacion = rjcdr_validar_rol($rol);
if (is_wp_error($validacion)) {
return $validacion;
}
remove_role($rol);
return null === get_role($rol)
? true
: new WP_Error('rjcdr_no_eliminado', __('No se pudo eliminar el rol.', 'rjc-delete-roles'));
}
function rjcdr_menu(): void
{
if (rjcdr_tiene_permiso()) {
add_management_page(
__('Limpieza de roles', 'rjc-delete-roles'),
__('Limpieza de roles', 'rjc-delete-roles'),
'manage_options',
'rjc-delete-roles',
'rjcdr_pagina'
);
}
}
add_action('admin_menu', 'rjcdr_menu');
function rjcdr_pagina(): void
{
if (!rjcdr_tiene_permiso()) {
wp_die(esc_html__('No tienes permisos suficientes.', 'rjc-delete-roles'), '', ['response' => 403]);
}
echo '<div class="wrap"><h1>' . esc_html__('Limpieza de roles', 'rjc-delete-roles') . '</h1>';
if (is_multisite()) {
echo '<p>' . esc_html__('Modo de consulta: el borrado está deshabilitado en multisitio.', 'rjc-delete-roles') . '</p>';
}
$estado = isset($_GET['rjcdr_status']) && is_string($_GET['rjcdr_status'])
? sanitize_key(wp_unslash($_GET['rjcdr_status'])) : '';
if ($estado === 'done' || $estado === 'failed') {
$mensaje = $estado === 'done'
? __('Rol eliminado.', 'rjc-delete-roles')
: __('No se pudo eliminar. Revisa el rol y recarga la página.', 'rjc-delete-roles');
echo '<div class="notice"><p>' . esc_html($mensaje) . '</p></div>';
}
echo '<table class="widefat striped"><thead><tr><th>' . esc_html__('Rol', 'rjc-delete-roles') . '</th><th>'
. esc_html__('Identificador', 'rjc-delete-roles') . '</th><th>' . esc_html__('Acción', 'rjc-delete-roles') . '</th></tr></thead><tbody>';
foreach (get_editable_roles() as $slug => $datos) {
$validacion = rjcdr_validar_rol($slug);
echo '<tr><td>' . esc_html(translate_user_role($datos['name'])) . '</td><td>' . esc_html($slug) . '</td><td>';
if (is_multisite()) {
echo esc_html__('Solo consulta.', 'rjc-delete-roles');
} elseif (is_wp_error($validacion)) {
echo esc_html($validacion->get_error_message());
} else {
echo '<form method="post" action="' . esc_url(admin_url('admin-post.php')) . '">';
echo '<input type="hidden" name="action" value="rjcdr_delete_role">';
echo '<input type="hidden" name="role" value="' . esc_attr($slug) . '">';
wp_nonce_field('rjcdr_delete_' . $slug);
submit_button(__('Eliminar este rol', 'rjc-delete-roles'), 'delete small', 'submit', false);
echo '</form>';
}
echo '</td></tr>';
}
echo '</tbody></table></div>';
}
function rjcdr_procesar_borrado(): void
{
$rol = isset($_POST['role']) ? wp_unslash($_POST['role']) : null;
$nonce = isset($_POST['_wpnonce']) ? wp_unslash($_POST['_wpnonce']) : null;
$resultado = rjcdr_eliminar_rol($rol, $nonce, $_SERVER['REQUEST_METHOD'] ?? '');
$url = add_query_arg(
'rjcdr_status',
is_wp_error($resultado) ? 'failed' : 'done',
admin_url('tools.php?page=rjc-delete-roles')
);
wp_safe_redirect($url);
exit;
}
add_action('admin_post_rjcdr_delete_role', 'rjcdr_procesar_borrado');
Los ejemplos anteriores son extractos de este mismo archivo: no los añadas una segunda vez. __() devuelve una cadena traducida; esc_html__() también la escapa para HTML. Para atributos y URL utilizamos esc_attr() y esc_url(). Traducir una cadena no equivale a escaparla.
Descargar el ejemplo revisado: rjc-delete-roles 2.0.0. El paquete contiene los mismos archivos mostrados y comprobados en esta revisión. Sustituye el enlace de descarga antiguo de la guía; no necesitas aquel ZIP para seguir estos pasos.
En una instalación de pruebas puedes instalar el ZIP desde Plugins y activarlo. Comprueba primero la página en Herramientas con roles de prueba, incluidos uno vacío y otro con usuarios. No es necesario activar este ejemplo en una web real para leer la guía o revisar su código.
Conclusión
Crear un plugin empieza por una cabecera y una estructura comprensible, pero una funcionalidad de administración también necesita autorización, validación y salida escapada. Las reglas de una operación deben comprobarse en el servidor aunque la interfaz ya impida seleccionarla.
El ejemplo se ha comprobado con las APIs de WordPress, verificando el método HTTP, los permisos, los nonces y las restricciones para eliminar roles protegidos o con usuarios asignados.
Estas pruebas no cubren la instalación completa ni la redirección del formulario en el navegador. El borrado en multisitio está deshabilitado en este ejemplo. Antes de adaptarlo a tu proyecto, pruébalo en una instalación de desarrollo y revisa cómo se asignan los usuarios y qué función cumple cada rol.
¿Tienes alguna pregunta?