Roles e Capabilities no WordPress é o conceito utilizado para tratar das permissões sobre as quais os são submetidos quando acessam e trabalham com o CMS.

Roles (Papéis ou funções, em tradução livre) são formadas por um conjunto de Capabilities (Capacidades, em tradução livre) que são as tarefas que um usuário tem permissão para realizar dentro do WordPress. Elas podem incluir praticamente tudo o que é relacionado ao CMS, como criar, editar e apagar posts, enviar imagens e assim por diante.

Neste artigo você vai aprender a trabalhar tanto com as permissões existentes no WordPress quanto com permissões customizadas, que você pode criar.

Então vamos lá!

Roles e Capabilities existentes no WordPress

O WordPress vem com várias permissões pré-definidas, das quais você já deve ter visto na sua área administrativa:

  • Administrador – Para um site único, tem todas as permissões sobre aquele site;
  • Editor – Podem gerenciar artigos criados por eles e por outros usuários (incluindo artigos privados). Podem utilizar a parte de multimídia do site.
  • Autor – Podem gerenciar apenas seus posts e também podem utilizar a parte de multimídia do site.
  • Colaborador – Podem gerenciar apenas seus posts e não podem utilizar a parte de multimídia do site.
  • Assinante – Podem gerenciar apenas seu perfil.

Quando falamos em MU (Rede de sites em apenas um WordPress), também existem os Super Administradores, que têm todas as permissões do Administrador, mais permissões para gerenciar a rede de sites.

Adicionando novas Capabilities em Roles existentes

Para adicionar novas Capabilities em roles existentes no WordPress, basta utilizar a função add cap, veja:

function adiciona_caps() {
    // Obtém a role de autor
    $role = get_role( 'author' );

    // Adiciona 
    $role->add_cap( 'edit_others_posts' ); 
}

// Agora os autores podem editar posts dos outros
add_action( 'admin_init', 'adiciona_caps');

A edição acima pode ser incluída tanto no seu functions.php quando no arquivo do seu plugin.

Observação importante: Isso só deve ser executado uma única vez, pois os valores são salvos na base de dados. Se você deixar esse trecho de código no seu functions.php, a nova capability será adiciona à base de dados a cada página acessada.

Removendo Capabilities de Roles existentes

Para remover a capability de uma Role existente, basta utilizar a função remove_cap, veja:

function remove_caps() {
    // Obtém a role de autor
    $role = get_role( 'author' );

    // Remove 
    $role->remove_cap( 'edit_others_posts' ); 
}

// Agora os autores NÃO podem editar posts dos outros
add_action( 'admin_init', 'remove_caps');

A edição acima pode ser incluída tanto no seu functions.php quando no arquivo do seu plugin.

Observação importante: Isso só deve ser executado uma única vez, pois os valores são acessados da base de dados. Se você deixar esse trecho de código no seu functions.php, a ação será executada a cada página acessada.

Verificando Capabilities Roles e Capabilities existentes

Para verificar se um usuário tem determinada permissão, utilize as funções user_can ou current_user_can, veja:

// Usuário pode moderar comentários?
if ( current_user_can('moderate_comments') ) {
    // Sim, esse pode
    echo 'Usuário pode moderar comentários.';
}

Isso pode ser incluído em qualquer parte do seu tema, tanto para bloquear usuários sem permissões quanto para liberar os que têm.

Se você quiser ver todas as Roles e Capabilities existentes que podem ser utilizadas no seu código, acesse Roles and Capabilities no WordPress Codex.

Criando Roles e Capabilities no WordPress

No WordPress é possível criar tanto Roles quanto Capabilities. Mas lembre-se da diferença entre ambas, Roles servem para agrupar Capabilities; Capabilities são as tarefas que o usuário tem permissão para realizar.

Veja como criar uma Roles e adicionar Capabilities na mesma.

add_role(
    'ajudante',
    __( 'Ajudante básico' ),
    array(
        'read'         => true,  // Pode ler
        'edit_posts'   => true,  // Pode editar posts
        'delete_posts' => false, // Não pode apagar posts
        'sorrir'       => true,  // Pode sorrir também (cap personalizada)
    )
);

Veja acima que criei uma “Role” e adicionei algumas Capabilities. Dentre elas adicionei “sorrir” (que pode ser utilizada como permissão personalizada).

Você pode checar isso de duas maneiras no seu tema ou plugin, tanto pela “Role” quanto “Capability”, veja:

// Se puder sorrir
if ( current_user_can('sorrir') ) {
    // Sorria
    echo 'Sorria!';
}

Ou pela “Role” completa, veja:

// Se puder
if ( current_user_can('ajudante') ) {
    // Sorria
    echo 'Sorria!';
}

Para remover é o mesmo esquema, veja como removemos a Rola “ajudante”:

remove_role('ajudante');

Já era, agora nenhum ajudando vai conseguir nem mesmo acessar a área administrativa.

Você também pode adicionar novas Capabilities nas “Roles” personalizadas.

$role = get_role('ajudante');

// Agora eles podem cantar também
$role->add_cap('cantar');

Agora temos além de “sorrir”, “cantar”.

Como adicionar Roles e Capabilities em usuários

Claro que você também pode adicionar Roles e Capabilities diretamente em usuários do seu WordPress, para isso faça o seguinte:

function adiciona_permissoes() {
    // Usuário atual
    $usuario = wp_get_current_user();
    
    // Adiciona uma "Role"
    $usuario->add_role('ajudante');
    
    // Adiciona uma "Cap"
    $usuario->add_cap('cantar');
}
add_action('init', 'adiciona_permissoes');

O trecho acima adiciona permissões no usuário atual (que está logado no WordPress), se quiser detalhar qual usuário deseja dar permissões, basta utilizar WP_User.

function adiciona_permissoes() {
    // Usuário atual
    $usuario = new WP_User(2);
    
    // Agora ele é administrador
    $usuario->add_role('administrator');
}
add_action('init', 'adiciona_permissoes');

Simples assim!

Depurando

É meio estranho criar coisas sem saber o que acontece, então aqui vai uma dica para você entender Roles e Capabilities no WordPress. Se você quiser visualizar tudo o que um usuário pode fazer no WordPress, basta fazer o seguinte:

function adiciona_permissoes() {
    // Usuário atual
    $usuario = new WP_User(2);
    
    // Mostra os dados
    print_r( $usuario );
}
add_action('init', 'adiciona_permissoes');

Assim você verá o seguinte:

WP_User Object
(
    [data] => stdClass Object
        (
            [ID] => 2
            [user_login] => teste
            [user_pass] => $P$BUoc5E3vG.YE/ZpK6/ltpCz59.H6LU0
            [user_nicename] => teste
            [user_email] => [email protected]
            [user_url] => 
            [user_registered] => 2014-10-06 17:10:40
            [user_activation_key] => 
            [user_status] => 0
            [display_name] => teste teste
        )

    [ID] => 2
    [caps] => Array
        (
            [ajudante] => 1
            [cantar] => 1
            [administrator] => 1
        )

    [cap_key] => wp_capabilities
    [roles] => Array
        (
            [0] => ajudante
            [2] => administrator
        )

    [allcaps] => Array
        (
            [read] => 1
            [edit_posts] => 1
            [delete_posts] => 1
            [sorrir] => 1
            [cantar] => 1
            [switch_themes] => 1
            [edit_themes] => 1
            [activate_plugins] => 1
            [edit_plugins] => 1
            [edit_users] => 1
            [edit_files] => 1
            [manage_options] => 1
            [moderate_comments] => 1
            [manage_categories] => 1
            [manage_links] => 1
            [upload_files] => 1
            [import] => 1
            [unfiltered_html] => 1
            [edit_others_posts] => 1
            [edit_published_posts] => 1
            [publish_posts] => 1
            [edit_pages] => 1
            [level_10] => 1
            [level_9] => 1
            [level_8] => 1
            [level_7] => 1
            [level_6] => 1
            [level_5] => 1
            [level_4] => 1
            [level_3] => 1
            [level_2] => 1
            [level_1] => 1
            [level_0] => 1
            [edit_others_pages] => 1
            [edit_published_pages] => 1
            [publish_pages] => 1
            [delete_pages] => 1
            [delete_others_pages] => 1
            [delete_published_pages] => 1
            [delete_others_posts] => 1
            [delete_published_posts] => 1
            [delete_private_posts] => 1
            [edit_private_posts] => 1
            [read_private_posts] => 1
            [delete_private_pages] => 1
            [edit_private_pages] => 1
            [read_private_pages] => 1
            [delete_users] => 1
            [create_users] => 1
            [unfiltered_upload] => 1
            [edit_dashboard] => 1
            [update_plugins] => 1
            [delete_plugins] => 1
            [install_plugins] => 1
            [update_themes] => 1
            [install_themes] => 1
            [update_core] => 1
            [list_users] => 1
            [remove_users] => 1
            [add_users] => 1
            [promote_users] => 1
            [edit_theme_options] => 1
            [delete_themes] => 1
            [export] => 1
            [wpseo_bulk_edit] => 1
            [ajudante] => 1
            [administrator] => 1
        )

    [filter] => 
)

É um objeto PHP comum. Então você pode visualizar qualquer coisa que preferir.

Claro que você não pode deixar isso no seu código, apenas visualize e remova.

O mesmo serve para as Roles e Capabilities, veja:

function ver_permissoes() {
    // Permissão de administrador
    $roles = get_role('administrator');
    
    // Mostra os dados
    print_r( $roles );
}
add_action('init', 'ver_permissoes');

Veja o que retorna:

WP_Role Object
(
    [name] => administrator
    [capabilities] => Array
        (
            [switch_themes] => 1
            [edit_themes] => 1
            [activate_plugins] => 1
            [edit_plugins] => 1
            [edit_users] => 1
            [edit_files] => 1
            [manage_options] => 1
            [moderate_comments] => 1
            [manage_categories] => 1
            [manage_links] => 1
            [upload_files] => 1
            [import] => 1
            [unfiltered_html] => 1
            [edit_posts] => 1
            [edit_others_posts] => 1
            [edit_published_posts] => 1
            [publish_posts] => 1
            [edit_pages] => 1
            [read] => 1
            [level_10] => 1
            [level_9] => 1
            [level_8] => 1
            [level_7] => 1
            [level_6] => 1
            [level_5] => 1
            [level_4] => 1
            [level_3] => 1
            [level_2] => 1
            [level_1] => 1
            [level_0] => 1
            [edit_others_pages] => 1
            [edit_published_pages] => 1
            [publish_pages] => 1
            [delete_pages] => 1
            [delete_others_pages] => 1
            [delete_published_pages] => 1
            [delete_posts] => 1
            [delete_others_posts] => 1
            [delete_published_posts] => 1
            [delete_private_posts] => 1
            [edit_private_posts] => 1
            [read_private_posts] => 1
            [delete_private_pages] => 1
            [edit_private_pages] => 1
            [read_private_pages] => 1
            [delete_users] => 1
            [create_users] => 1
            [unfiltered_upload] => 1
            [edit_dashboard] => 1
            [update_plugins] => 1
            [delete_plugins] => 1
            [install_plugins] => 1
            [update_themes] => 1
            [install_themes] => 1
            [update_core] => 1
            [list_users] => 1
            [remove_users] => 1
            [add_users] => 1
            [promote_users] => 1
            [edit_theme_options] => 1
            [delete_themes] => 1
            [export] => 1
            [wpseo_bulk_edit] => 1
        )

)

Todas as permissões presentes na “Role” Administrador.

Considerações finais

Lembre-se que todas as Roles e Capabilities são salvas na base de dados, portanto, seu código deve ser executado apenas uma única vez. Se você estiver criando um plugin, poderá utilizar o gancho register activation hook. Se for um tema, faça apenas após a instalação, por exemplo:

add_action('after_theme_setup','executa_apos_instalar_tema');
function executa_apos_instalar_tema(){
    if ( isset($_GET['activated']) && $_GET['activated'] == 'true' ){
        // Seu código aqui.
    }
}

É meio que uma “gambiarra”, mas funciona na maioria dos casos.

Em caso de dúvidas, não hesite em comentar.