Come creare una capability personalizzata per un ruolo?

Per un plugin su cui sto attualmente lavorando, volevo concedere/restringere l'accesso alle impostazioni del plugin (cioè, le relative pagine del menu di amministrazione) in base ai ruoli.
Per questo motivo, ho dovuto aggiungere una nuova capability specifica del plugin ai ruoli utente.

Sfortunatamente, la risposta di kaiser sembra non funzionare più, quindi ho passato del tempo a cercare di capire come implementare la funzionalità descritta sopra.

Il Piano

Prima di condividere il codice con voi, ecco di cosa si tratta, in linguaggio semplice:

1. All'attivazione del plugin, aggiungi la nuova capability LA_NUOVA_CAP ai ruoli che hanno una determinata capability integrata CAP_INTEGRATA (nel mio caso: edit_pages).
2. Ad ogni caricamento di pagina, esegui il punto 1. (cioè, aggiungi nuovamente la capability). Questo è necessario solo se vuoi tenere conto di eventuali nuovi ruoli creati dopo l'attivazione del plugin. Questi nuovi ruoli non avranno la capability specifica del plugin, anche se hanno la capability integrata richiesta.
3. Usa la nuova capability per qualsiasi cosa tu voglia. Come spiegato prima, la uso per concedere/restringere l'accesso alle pagine del menu di amministrazione del plugin, ed è così che viene implementato nell'esempio di codice seguente.
4. Alla disattivazione del plugin, rimuovi la capability. Ovviamente, potresti farlo anche durante la disinstallazione del plugin. In ogni caso, fallo prima o poi.

Il Codice

Ed ecco la lista sopra convertita in codice:

» Configurazione

class WPSE35165Plugin {

    public function __construct() {
        // Registra gli hook
        register_activation_hook(__FILE__, array(__CLASS__, 'activation'));
        register_deactivation_hook(__FILE__, array(__CLASS__, 'deactivation'));

        // Aggiungi azioni
        add_action('admin_menu', array(__CLASS__, 'admin_menu'));
    }

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

    // Aggiungi la nuova capability a tutti i ruoli che hanno una determinata capability integrata
    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('CAP_INTEGRATA')) {
                $role->add_cap('LA_NUOVA_CAP');
            }
        }
    }

» Utilizzo

    // Aggiungi pagine del menu del plugin al menu di amministrazione
    public function admin_menu() {
        // Rimuovi la riga seguente se non ti interessa gestire nuovi ruoli
        // creati dopo l'attivazione del plugin
        self::add_cap();

        // Configura il menu di amministrazione del plugin
        add_menu_page('Menu', 'Menu', 'LA_NUOVA_CAP', …);
        add_submenu_page('wpse35165', 'Sottomenu', 'Sottomenu', 'LA_NUOVA_CAP', ...);
    }

» Pulizia

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

    // Rimuovi la capability specifica 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('LA_NUOVA_CAP')) {
                $role->remove_cap('LA_NUOVA_CAP');
            }
        }
    }

}

Nota: Per favore non usare capability in maiuscolo. Questo è solo per migliorare la leggibilità.

Rimuovi ciò che aggiungi

Innanzitutto, assicurati che tutto ciò che aggiungi durante l'attivazione venga anche rimosso durante la disinstallazione. Ho preparato un breve tutorial con codice di esempio per te.

Test con un piccolo plugin:

Non conosco molto delle funzionalità MU, ma per quanto ne so, l'oggetto dei ruoli è globale su tutti i blog. Prova questo piccolo plugin e vedi cosa riesci a ottenere:

<?php
/*
Plugin Name:    MU Roles check
Plugin URI:     https://github.com/franz-josef-kaiser/
Description:    Verifica i ruoli durante la visualizzazione di 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
*/

/**
 * Mostra i dati del blog e i nomi dei ruoli in questo blog
 * Mostra anche se la capability personalizzata è stata aggiunta con successo, oppure mostra n/a per il ruolo
 * 
 * @return void
 */
function wpse35165_role_check()
{
    $blog = get_current_site();
    $custom_cap = 'name_of_your_custom_capability';

    $html = "<hr /><table>";
    $html .= "<caption>Elenco ruoli in (Blog) {$blog->site_name} / ID#{$blog->id}</caption>"
    $html .= "<thead><tr><th>Nome Ruolo</th><th>Capabilities</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' );

Aggiungere Capabilities

/**
 * Aggiunge la capability agli oggetti ruolo
 * Dovrebbe essere nella tua funzione di attivazione e eseguito prima di ispezionare con il tuo plugin
 * 
 * @return void
 */
function wpse35165_add_cap()
{
    $custom_cap = 'name_of_your_custom_capability';
    $min_cap    = 'the_minimum_required_built_in_cap'; // Controlla "Roles and objects table" nel 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: Puoi aggiungere la capability al ruolo senza concedere l'accesso - basta impostare il secondo argomento $grant = false;. Questo permette di abilitare singoli utenti aggiungendo semplicemente la cap con l'ultimo argomento impostato a true.

Funziona per me:

add_action('admin_init', 'add_custom_cap');
function add_custom_cap()
{
  $custom_cap = 'test_cap'; // Capacità personalizzata da aggiungere
  $min_cap    = 'read';     // Capacità minima richiesta
  $grant      = true;       // Concedi la capacità
  $to_role = 'your_user_role'; // Ruolo utente target
  $role = 'user_role';      // Ruolo base

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