Contents
Introducción
WordPress incluye desde hace varias versiones la pantalla Site Health (Salud del sitio), una herramienta que evalúa configuraciones, rendimiento y seguridad. Para desarrolladores es posible ampliar esa evaluación registrando comprobaciones (health checks) personalizadas con PHP. Este artículo explica con todo lujo de detalles cómo funciona la API de comprobaciones, cómo registrar tests síncronos y asíncronos, el formato de los resultados y buenas prácticas para evitar impacto en el rendimiento y mantener la seguridad.
Conceptos básicos: cómo Site Health ejecuta las comprobaciones
- Tipos de comprobación: existen dos categorías principales cuando se registran tests: direct (síncronos) y async (asíncronos). Las direct se ejecutan inmediatamente en el servidor cuando se carga la pantalla las async son solicitadas por el navegador y ejecutadas en segundo plano mediante peticiones específicas, evitando bloquear la interfaz.
- Filtro principal: para añadir, modificar o eliminar tests se utiliza el filtro site_status_tests. Este filtro recibe y debe devolver un array con la estructura que veremos más abajo.
- Formato de la respuesta de un test: cada test debe devolver un array con clave status y otros campos opcionales (label, description, actions, badge). Los valores comunes para status son: good, recommended y critical.
Registrar una comprobación: la estructura del filtro
La forma general de añadir tests es enganchar una función al filtro site_status_tests y añadir tu grupo y tests dentro de las claves direct o async. El array devuelto debe respetar la estructura que WordPress espera: cada grupo tiene un label y un array tests con identificadores y callbacks.
Ejemplo minimalista: registro de tests (estructura)
__( Comprobaciones de Mi Plugin, mi-plugin ),
tests => array(
mi_plugin_check_direct => array(
label => __( Verificar acceso a la carpeta de datos, mi-plugin ),
test => mi_plugin_check_direct_callback,
),
),
)
// Grupo de comprobaciones asíncronas (para verificaciones que pueden tardar)
tests[async][mi_plugin] = array(
label => __( Comprobaciones en segundo plano de Mi Plugin, mi-plugin ),
tests => array(
mi_plugin_check_async => array(
label => __( Comprobar API remota, mi-plugin ),
test => mi_plugin_check_async_callback,
),
),
)
return tests
}
?>
Implementar un test directo (síncrono)
Los tests directos deben ser rápidos y no realizar operaciones de red ni consultas pesadas. Úsalos para comprobar permisos, variables de configuración, existencia de archivos, versiones, etc.
Ejemplo: comprobar que un directorio de datos es escribible
__( Directorio de datos inaccesible, mi-plugin ),
status => critical,
description => __( No se puede crear o escribir en la carpeta de datos. Verifica permisos de archivos., mi-plugin ),
actions => array(
array(
label => __( Abrir documentación, mi-plugin ),
url => https://example.com/mi-plugin/docs,
),
),
)
}
}
if ( ! is_writable( data_dir ) ) {
return array(
label => __( Directorio de datos no escribible, mi-plugin ),
status => recommended,
description => __( La carpeta existe pero no tiene permisos de escritura. Ajusta chmod/propietario., mi-plugin ),
)
}
return array(
label => __( Directorio de datos OK, mi-plugin ),
status => good,
)
}
?>
Implementar un test asíncrono (async)
Los tests asíncronos se usan para tareas costosas: peticiones a APIs externas, pruebas de latencia, operaciones que se deben ejecutar sin bloquear la carga de la página. El flujo es: WordPress registra la comprobación como async y el navegador solicitará su ejecución la respuesta debe tener la misma estructura de resultado que un test directo (status, label, description…).
Ejemplo: comprobar un endpoint remoto con wp_remote_get
10 ) )
if ( is_wp_error( response ) ) {
return array(
label => __( API remota no disponible, mi-plugin ),
status => critical,
description => sprintf(
/ translators: %s: mensaje del error /
__( No se pudo conectar con la API remota: %s, mi-plugin ),
esc_html( response->get_error_message() )
),
)
}
code = wp_remote_retrieve_response_code( response )
if ( 200 !== (int) code ) {
return array(
label => __( API remota respondió con error, mi-plugin ),
status => recommended,
description => sprintf(
/ translators: %s: código HTTP /
__( La API respondió con el código %s. Revisa la configuración., mi-plugin ),
esc_html( code )
),
)
}
// Opcional: validar cuerpo si necesario
body = wp_remote_retrieve_body( response )
if ( empty( body ) ) {
return array(
label => __( Respuesta vacía de la API, mi-plugin ),
status => recommended,
description => __( La API respondió correctamente pero el cuerpo está vacío., mi-plugin ),
)
}
return array(
label => __( API remota accesible, mi-plugin ),
status => good,
description => __( Se recibió una respuesta correcta de la API., mi-plugin ),
)
}
?>
Formato de la respuesta: claves útiles y su significado
- status (obligatorio): good, recommended o critical. Es la semántica que Site Health usa para mostrar iconos y recomendaciones.
- label (recomendado): una etiqueta corta del resultado.
- description (opcional): HTML con una explicación detallada de la comprobación y posibles soluciones. Aquí puedes incluir pasos para corregir el problema o mensajes para administradores.
- actions (opcional): para ofrecer enlaces o botones que permitan al usuario solucionar el problema. Se estructuran como arrays con al menos label y url.
- badge (opcional): un array para resaltar información adicional (no todos los temas lo muestran igual).
Registrar información de depuración adicional
Además de las comprobaciones, puedes añadir secciones a la pestaña Información de Site Health usando el filtro debug_information. Esto es útil para mostrar versiones, configuración o datos técnicos que faciliten soporte.
__( Mi Plugin, mi-plugin ),
fields => array(
version => array(
label => __( Versión, mi-plugin ),
value => 1.2.3,
),
endpoint => array(
label => __( Endpoint configurado, mi-plugin ),
value => esc_url( get_option( mi_plugin_endpoint ) ),
),
),
)
return info
}
?>
Buenas prácticas y recomendaciones
- Evitar operaciones caras en tests directos: las comprobaciones síncronas deben ser rápidas. Para tareas que impliquen I/O o red usa async.
- Cachear resultados: si tu comprobación hace operaciones costosas (por ejemplo consultas externas), usa transients para almacenar el resultado durante un tiempo razonable y reducir peticiones repetidas.
- Validar y sanear salidas: cualquier dato mostrado en la description o label debe sanearse (esc_html, esc_url) ya que se mostrará en el administrador.
- Internacionalización: usa funciones __(), _e(), etc., y prepara tus textos para traducirlos.
- Seguridad: no expongas claves, tokens ni datos sensibles en la descripción de las comprobaciones o en debug_information.
- Compatibilidad: comprueba que tu código sólo se ejecuta en contexto admin y con las capacidades adecuadas (por ejemplo current_user_can(activate_plugins) o manage_options si procede).
Patrones avanzados
- Probar en background con WP-Cron o transients: para comprobaciones programadas que no dependan de la visita del admin, programa un evento cron que actualice un transient con el estado y que el test (direct o async) lea ese transient.
- Integración con REST API: si necesitas tests sofisticados, registra un endpoint REST privado que ejecute las comprobaciones con controles de permiso y devuelve JSON que tu callback async consumirá.
- Eliminar o desactivar tests: para permitir compatibilidad con otras extensiones, documenta cómo desactivar tus comprobaciones y ofrece filtros para personalizar el comportamiento.
Ejemplo avanzado: usar transients para no repetir comprobaciones remotas
__( Comprobando API remota…, mi-plugin ),
status => recommended,
)
response = wp_remote_get( https://api.example.com/health, array( timeout => 10 ) )
if ( is_wp_error( response ) ) {
result = array(
label => __( API remota no disponible, mi-plugin ),
status => critical,
description => esc_html( response->get_error_message() ),
)
} else {
code = wp_remote_retrieve_response_code( response )
if ( 200 === (int) code ) {
result = array(
label => __( API remota OK, mi-plugin ),
status => good,
description => __( Se obtuvo respuesta 200 de la API remota., mi-plugin ),
)
} else {
result = array(
label => __( API remota respondió con error, mi-plugin ),
status => recommended,
description => sprintf( __( Código HTTP: %s, mi-plugin ), esc_html( code ) ),
)
}
}
// Guardar resultado 10 minutos
set_transient( cache_key, result, 10 MINUTE_IN_SECONDS )
return result
}
?>
Depuración y pruebas
- Activa WP_DEBUG en tu entorno de desarrollo para ver errores PHP si tu callback falla.
- Usa logging (error_log o funciones del plugin de debug) para inspeccionar flujos asíncronos que se ejecuten fuera de la petición principal.
- Verifica que las comprobaciones aparecen en Herramientas → Salud del sitio. Para tests async, abre la pestaña Comprobaciones y observa la ejecución en segundo plano.
Resumen
Registrar health checks personalizados en Site Health te permite integrar comprobaciones específicas de tu plugin o tema en la experiencia de mantenimiento de WordPress. Usa el filtro site_status_tests para añadir tests directos y async, devuelve resultados con status, label y description, y sigue buenas prácticas (usar async o transients para operaciones costosas, sanear salidas, y no exponer información sensible). Con los ejemplos anteriores tendrás una base sólida para crear comprobaciones robustas, seguras y eficientes.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |