Como registrar una taxonomía personalizada jerárquica en PHP en WordPress

Introducción

Registrar una taxonomía personalizada jerárquica en WordPress es una tarea habitual cuando se necesita organizar contenido más allá de las categorías y etiquetas por defecto. Una taxonomía jerárquica permite términos padre/hijo —como categorías— y ofrece URLs anidadas, interfaz administrativa similar a Categorías y control más fino sobre las consultas y la REST API.

Requisitos previos

• Tener acceso al archivo functions.php del tema hijo o crear un plugin propio (recomendado para portar el código entre temas).
• Conocimientos básicos de PHP y la estructura de WordPress (hooks, filtros, CPTs).
• Si se desea usar la taxonomía con un Custom Post Type, este debe estar registrado antes, o asociarse en el hook adecuado.

Conceptos clave

• hierarchical: true indica que la taxonomía admite jerarquía (términos padre/hijo).
• labels: array con los textos que aparecerán en el admin y en la UI.
• rewrite: controla las reglas de URL. El parámetro hierarchical dentro de rewrite permite URLs anidadas.
• show_in_rest: true para exponer la taxonomía en la REST API (útil con el editor de bloques).
• capabilities: mapea permisos para quien pueda gestionar/editar/atribuir términos.
• show_admin_column: muestra una columna con la taxonomía en la pantalla de listados de posts.

Ejemplo práctico: registrar una taxonomía jerárquica Género para un CPT libro

En este ejemplo registramos una taxonomía llamada genero para el CPT libro. El código puede ir en el functions.php de un tema hijo o dentro de un plugin. Recomendación: si lo pones en un plugin, usar flush_rewrite_rules() solo en la activación del plugin.

 Géneros,
        singular_name     => Género,
        search_items      => Buscar géneros,
        all_items         => Todos los géneros,
        parent_item       => Género padre,
        parent_item_colon => Género padre:,
        edit_item         => Editar género,
        update_item       => Actualizar género,
        add_new_item      => Añadir nuevo género,
        new_item_name     => Nombre del nuevo género,
        menu_name         => Géneros,
    )

    args = array(
        labels            => labels,
        hierarchical      => true,               // clave: jerárquica como categorías
        public            => true,
        show_ui           => true,
        show_in_rest      => true,               // exponer en REST API (Gutenberg)
        show_admin_column => true,               // columna en la lista de posts
        query_var         => true,
        rewrite           => array(
            slug        => libro/genero,      // slug personalizado en las URLs
            with_front  => false,
            hierarchical=> true,                // permite URLs de términos anidados
        ),
    )

    register_taxonomy( genero, array( libro ), args )
}
add_action( init, mi_registrar_taxonomia_genero )
?>

Explicación rápida del ejemplo

• labels: traducen las cadenas que aparecen en el admin.
• hierarchical => true: hace la taxonomía anidada (padre/hijo).
• show_in_rest => true: permite usar la taxonomía desde el editor de bloques y la REST API.
• rewrite con hierarchical => true y un slug compuesto permite URLs del tipo: /libro/genero/padre/hijo/

Flush de reglas de reescritura: precauciones

No uses flush_rewrite_rules() en cada carga (por ejemplo dentro de init) porque es costoso. Si registras la taxonomía desde un plugin, haz flush solo en la activación del plugin:

Opciones avanzadas y mapeo de capacidades

Si quieres controlar permisos más finos, puedes mapear capabilities:

 array(
        manage_terms  => manage_generos,
        edit_terms    => edit_generos,
        delete_terms  => delete_generos,
        assign_terms  => assign_generos,
    ),
)
register_taxonomy( genero, array( libro ), args )

// Con un role específico se pueden asignar permisos:
// role = get_role(editor)
// role->add_cap(manage_generos)
// role->add_cap(edit_generos)
?>

Trabajar con términos en plantillas

Al mostrar términos en la plantilla single-libro.php o en listados, se emplean funciones como wp_get_post_terms() o get_the_terms(). Ejemplos de uso:

    foreach ( generos as genero ) {
        term_link = get_term_link( genero )
        echo 
 . esc_html( genero->name ) . 
    }
    echo 
}

// Mostrar una lista de términos en una plantilla (jerarquía incluida)
wp_list_categories( array(
    taxonomy => genero,
    title_li => ,
) )
?>

Insertar términos programáticamente

Para crear términos desde código o durante importaciones:

 parent_term[term_id],
    ) )
}
?>

Compatibilidad con la REST API

Si show_in_rest => true se podrán realizar peticiones REST para listar, crear y actualizar términos. Puedes personalizar el rest_base si quieres una ruta distinta:

 true,
    rest_base    => generos-api,
    // rest_controller_class => WP_REST_Terms_Controller, // opcional
)
register_taxonomy( genero, array( libro ), args )
?>

Buenas prácticas

• Registrar taxonomías desde un plugin siempre que la lógica se deba mantener al cambiar de tema.
• Evitar cambies bruscos en slugs en sitios en producción sin redirecciones las URLs de términos cambian y pueden romper enlaces y SEO.
• Usar traducciones y funciones de internacionalización (_x(), __()) si el proyecto será multilingüe.
• Limitar flush_rewrite_rules() a activaciones/desactivaciones de plugins.
• Comprobar compatibilidad con plugins de caché y con el rewrite para que las URLs jerárquicas funcionen correctamente.

Errores comunes y soluciones

• No aparece la columna en el listado de posts: comprobar show_admin_column => true y limpiar cachés.
• URLs 404 tras cambiar slugs: ejecutar manualmente Ajustes → Enlaces permanentes o flush_rewrite_rules() en activación.
• Términos no jerárquicos pese a hierarchical => true: confirmar que los términos se crean con parent si corresponde y que no hay conflictos con plugins que alteren taxonomías.
• Problemas en REST API: verificar show_in_rest => true y que rest_base no colisione con otras rutas.

Resumen

Registrar una taxonomía personalizada jerárquica en WordPress implica configurar correctamente labels, args y decidir si estará disponible en la REST API. Usar hierarchical => true y rewrite con hierarchical => true permite aprovechar la estructura padre/hijo tanto en admin como en URLs. Sitúe el código en un plugin si desea portabilidad y haga flush de las reglas de reescritura únicamente en activación.

Ejemplo final compacto (lista de pasos)

1. Registrar la taxonomía en init con register_taxonomy.
2. Configurar hierarchical => true y rewrite => array(hierarchical => true).
3. Habilitar show_in_rest si se utiliza Gutenberg o la REST API.
4. Usar register_activation_hook en plugins para flush_rewrite_rules().
5. Usar funciones como wp_get_post_terms(), get_term_link() y wp_insert_term() para consumir/crear términos.

Enlaces útiles

• Documentación oficial: register_taxonomy
• Documentación REST API de WordPress
• Hooks y filtros en WordPress

	Acepto donaciones de BAT's mediante el navegador Brave 🙂