¿Cómo crear una capacidad personalizada de rol?

Para un plugin en el que estoy trabajando actualmente, quería otorgar/restringir el acceso a la configuración del plugin (es decir, a las páginas del menú de administración correspondientes) por rol.
Por lo tanto, tuve que agregar una nueva capability específica del plugin a los user roles.

Desafortunadamente, la respuesta de kaiser parece no funcionar más, así que pasé un tiempo tratando de descubrir cómo permitir la funcionalidad mencionada anteriormente.

El Plan

Antes de compartir mi código con ustedes, aquí está de qué se trata, en texto claro:

1. Al activar el plugin, agregar la nueva capacidad THE_NEW_CAP a los roles que tienen una determinada capacidad incorporada BUILT_IN_CAP (en mi caso: edit_pages).
2. En cada carga de página, hacer 1. (es decir, agregar la capacidad nuevamente). Esto solo es necesario si deseas tener en cuenta posibles nuevos roles que se hayan creado después de la activación del plugin. Por lo tanto, estos nuevos roles no tienen la capacidad específica del plugin, incluso si tienen la capacidad incorporada requerida.
3. Usar la nueva capacidad para lo que desees. Como se explicó antes, yo la uso para otorgar/restringir el acceso a las páginas del menú de administración del plugin, así es como se hace en el siguiente ejemplo de código.
4. Al desactivar el plugin, eliminar la capacidad. Por supuesto, también podrías hacer esto cuando el plugin se desinstale. De cualquier manera, hazlo eventualmente.

El Código

Y aquí está la lista anterior convertida en código:

» Configurándolo

class WPSE35165Plugin {

    public function __construct() {
        // Registrar hooks
        register_activation_hook(__FILE__, array(__CLASS__, 'activation'));
        register_deactivation_hook(__FILE__, array(__CLASS__, 'deactivation'));

        // Agregar acciones
        add_action('admin_menu', array(__CLASS__, 'admin_menu'));
    }

    public function activation() {
        self::add_cap();
    }

    // Agregar la nueva capacidad a todos los roles que tienen una cierta capacidad incorporada
    private static function add_cap() {
        $roles = get_editable_roles();
        foreach ($GLOBALS['wp_roles']->role_objects as $key => $role) {
            if (isset($roles[$key]) && $role->has_cap('BUILT_IN_CAP')) {
                $role->add_cap('THE_NEW_CAP');
            }
        }
    }

» Usándolo

    // Agregar páginas del menú del plugin al menú de administración
    public function admin_menu() {
        // Elimina la siguiente línea si no te importan los nuevos roles
        // que se hayan creado después de la activación del plugin
        self::add_cap();

        // Configurar el menú de administración del plugin
        add_menu_page('Menú', 'Menú', 'THE_NEW_CAP', …);
        add_submenu_page('wpse35165', 'Submenú', 'Submenú', 'THE_NEW_CAP', ...);
    }

» Limpiándolo

    public function deactivation() {
        self::remove_cap();
    }

    // Eliminar la capacidad personalizada específica del plugin
    private static function remove_cap() {
        $roles = get_editable_roles();
        foreach ($GLOBALS['wp_roles']->role_objects as $key => $role) {
            if (isset($roles[$key]) && $role->has_cap('THE_NEW_CAP')) {
                $role->remove_cap('THE_NEW_CAP');
            }
        }
    }

}

Nota: Por favor, no uses capacidades en mayúsculas. Esto es solo para legibilidad.

Elimina lo que agregas

Primero, asegúrate de que todo lo que agregues durante la activación también sea eliminado durante la desinstalación. Tengo un breve tutorial que incluye código de ejemplo para ti.

Prueba con un pequeño plugin:

No sé mucho sobre MU, pero por lo que entiendo, el objeto de roles es global en todos los blogs. Prueba este pequeño plugin y observa lo que obtienes:

<?php
/*
Plugin Name:    Verificador de roles MU
Plugin URI:     https://github.com/franz-josef-kaiser/
Description:    Verifica los roles al visualizar un blog
Author:         Franz Josef Kaiser
Author URI:     https://plus.google.com/u/0/107110219316412982437
Version:        0.1
Text Domain:    murc
License:        GPL v2 - http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
*/

/**
 * Muestra los datos del blog y los nombres de roles en este blog
 * También muestra si la capacidad personalizada fue agregada exitosamente, o muestra n/a para el rol
 * 
 * @return void
 */
function wpse35165_role_check()
{
    $blog = get_current_site();
    $custom_cap = 'nombre_de_tu_capacidad_personalizada';

    $html = "<hr /><table>";
    $html .= "<caption>Lista de roles en (Blog) {$blog->site_name} / ID#{$blog->id}</caption>"
    $html .= "<thead><tr><th>Nombre del Rol</th><th>Capacidades</th></tr></thead><tbody>";
    foreach ( $GLOBALS['wp_roles'] as $name => $role_obj )
    {
        $cap = in_array( $custom_cap, $role_obj->caps ) ? $custom_cap : 'n/a';
        $cap = $cap OR in_array( $custom_cap, $role_obj->allcaps ) ? $custom_cap : 'n/a';
        $html .= "<tr><td>{$name}</td><td>{$cap}</td></tr>";
    }
    $html .= '</tbody></table>';

    print $html;
}
add_action( 'shutdown', 'wpse35165_role_check' );

Agregando Capacidades

/**
 * Agrega la capacidad a los objetos de roles
 * Debe estar en tu función de activación y hacerse antes de inspeccionar con tu plugin
 * 
 * @return void
 */
function wpse35165_add_cap()
{
    $custom_cap = 'nombre_de_tu_capacidad_personalizada';
    $min_cap    = 'la_capacidad_minima_requerida_integrada'; // ¡Revisa la "Tabla de roles y objetos" en el codex!
    $grant      = true; 

    foreach ( $GLOBALS['wp_roles'] as $role_obj )
    {
        if ( 
            ! $role_obj->has_cap( $custom_cap ) 
            AND $role_obj->has_cap( $min_cap )
        )
            $role_obj->add_cap( $custom_cap, $grant );
    }
}

Nota: Puedes agregar la capacidad al rol sin otorgar acceso a ella - simplemente establece el segundo argumento $grant = false;. Esto permite incluir usuarios individuales en una lista blanca simplemente agregando la capacidad con el último argumento como true.

Esto funciona para mí:

add_action('admin_init', 'add_custom_cap');
function add_custom_cap()
{
  // Definir la capacidad personalizada que queremos añadir
  $custom_cap = 'test_cap';
  // Capacidad mínima requerida para asignar la nueva capacidad
  $min_cap    = 'read';
  // Si se concede o no la capacidad
  $grant      = true;
  // Rol de usuario al que queremos añadir la capacidad
  $to_role = 'your_user_role';
  $role = 'user_role';

  // Iterar a través de todos los roles disponibles
  foreach ( $GLOBALS['wp_roles'] as $role_obj )
  {
    // Verificar si el objeto de rol existe
    if (is_object($role_obj[$role])) {
      // Comprobar si el rol no tiene la capacidad personalizada pero sí tiene la capacidad mínima requerida
      if (!$role_obj[$role]->has_cap( $custom_cap ) && $role_obj[$role]->has_cap( $min_cap )) {
        // Añadir la capacidad personalizada al rol
        $role_obj[$role]->add_cap( $custom_cap, $grant );
      }
    }
  }
}