Contents
Introducción
En WordPress, el filtro the_content es una herramienta poderosa para modificar o inyectar contenido dinámicamente en las entradas y páginas antes de que se muestren al visitante. Este artículo explica en detalle cómo usar ese filtro en PHP, buenas prácticas, compatibilidad con el editor de bloques (Gutenberg), problemas habituales y ejemplos prácticos listos para copiar.
Qué es el filter the_content y cuándo usarlo
the_content es un hook de tipo filter que recibe el HTML final que representa el contenido de una entrada (post content). Si necesitas agregar anuncios, avisos, enlaces relacionados, bloques dinámicos o contenido personalizado sin editar la plantilla del tema, inyectar mediante the_content es la forma recomendada porque actúa justo antes de mostrar el contenido.
Firma básica
Un filtro típico se añade con add_filter y recibe el contenido como primer argumento. Debes devolver siempre el contenido (modificado o no).
Buenas prácticas al usar the_content
- Comprobar el contexto: limitar la modificación solo cuando corresponda (is_singular, is_main_query, in_the_loop).
- Evadir bucles infinitos: nunca llamar a apply_filters(the_content, …) dentro del propio filtro sin eliminar temporalmente el filtro.
- Sanitizar: limpiar contenido externo con wp_kses_post o funciones apropiadas.
- Compatibilidad con bloques: detectar bloques y actuar con precaución (has_block).
- Performance: evitar cálculos pesados en cada carga cachear resultados cuando sea posible.
Ejemplos prácticos
1) Añadir solo en entradas individuales (single posts)
Si quieres añadir un aviso solo en entradas individuales y en la consulta principal:
2) Insertar contenido tras el primer párrafo
Un patrón frecuente es colocar un anuncio o una llamada a la acción justo después del primer ltpgt del contenido. La siguiente técnica usa preg_replace para insertar después del primer cierre de párrafo.
, la 1 limita la sustitución al primer match
content = preg_replace(/(lt/pgt)/i, 1 . insercion, content, 1)
return content
}
?>
3) Recuperar metadatos del post y mostrarlos
Ejemplo que inyecta contenido personalizado almacenado en un campo personalizado (meta):
ID, mi_banner, true)
if (empty(valor)) {
return content
}
// Sanitizar el HTML guardado en el meta (permitir solo etiquetas seguras)
valor = wp_kses_post(valor)
return valor . content
}
?>
4) Evitar recursión si necesitas procesar shortcodes o filtros adicionales
Si necesitas aplicar filtros al contenido adicional que vas a inyectar y eso implicara llamar a the_content de nuevo, hay que eliminar el filtro temporalmente para evitar llamadas infinitas.
Compatibilidad con Gutenberg (editor de bloques)
Gutenberg puede producir contenido que no incluya etiquetas ltpgt de forma directa (especialmente si el bloque principal es HTML personalizado o bloques anidados). Algunas recomendaciones:
- Comprobar si existen bloques concretos con has_block(core/paragraph, post->post_content).
- Evitar suposiciones rígidas sobre la estructura HTML usar condiciones alternativas si no hay ltpgt.
- Si tu inyección es un bloque completo, considera registrar un bloque o un bloque dinámico en lugar de usar the_content.
Sanitización y seguridad
Cuando se inyecta HTML dinámico o procedente de fuentes externas (APIs, campos personalizados, entradas de usuarios), debe sanearse. Algunas funciones útiles:
- wp_kses_post(html) — permite las etiquetas HTML que WordPress permite en post content.
- wp_kses(html, allowed) — definir conjunto de etiquetas/atributos permitidos.
- esc_url() — para limpiar URLs en atributos href/src.
ID, codigo_html, true) clean = wp_kses_post(raw) // Acepta solo etiquetas seguras content = clean . content ?>
Prioridad del filtro y orden de ejecución
La prioridad (tercer parámetro de add_filter) determina en qué punto se ejecuta tu filtro respecto a otros. Un valor bajo (ej. 5) ejecuta antes uno alto (ej. 20) después. Útil para:
- Insertar contenido antes de que otros plugins transformen el HTML.
- Esperar a que shortcodes u otros filtros hayan actuado antes de tu inserción.
Rendimiento y caching
- Evita consultas pesadas (consultas adicionales a la base de datos, llamadas a APIs externas) directamente desde el filtro en cada carga. Usa transients o cache a nivel de objeto cuando sea posible.
- Si la inyección es estática por post, calcula y guarda el resultado en post meta o transient cuando el post se guarda o actualiza.
Problemas comunes y cómo resolverlos
- Contenido duplicado: comprueba prioridades y que no haya más filtros haciendo la misma tarea.
- Shortcodes no procesados en la inyección: usa do_shortcode() sobre la cadena antes de devolverla.
- HTML roto por wpautop: prueba a aplicar o suprimir wpautop según la estructura a veces conviene envolver en contenedores.
- Inyección en feeds o REST API: restringe con condiciones como is_feed() o rest_is_request() según convenga.
Ejemplo completo: inyectar anuncio solo en post, tras primer párrafo, con cache y sanitización
ID
insercion = get_transient(cache_key)
if (false === insercion){
// Simular generación de anuncio (podría venir de API)
raw = ltdiv class=anunciogtlth3gtPatrocinadolt/h3gtltpgtCompra ahoralt/pgtlt/divgt
// Sanitizar
insercion = wp_kses(raw, array(
div =gt array(class => array()),
h3 =gt array(),
p =gt array()
))
// Cachear por una hora
set_transient(cache_key, insercion, HOUR_IN_SECONDS)
}
// Insertar después del primer párrafo
content = preg_replace(/(lt/pgt)/i, 1 . insercion, content, 1)
return content
}
?>
Resumen
El filtro the_content es ideal para inyectar contenido dinámico sin tocar los archivos de plantilla. Respeta siempre el contexto (is_singular, in_the_loop, is_main_query), evita la recursión, sanitiza cualquier HTML externo y considera la compatibilidad con Gutenberg y el impacto en rendimiento. Con estas pautas y los ejemplos mostrados puedes implementar inyecciones seguras y eficientes en WordPress.
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |