Roles e capabilities no WordPress

Roles, traduzidos para português como funções, é uma forma de fazer a autorização de usuários, isto é, garantir que determinado usuário tenha acesso a X funcionalidades, dependendo das suas necessidades. No WordPress, por padrão, são criados seis (6) funções: assinante, colaborador, autor,  editor, admin e super admin [1] (usado quando a função multisite está ativa).

Porém, nem sempre a configuração padrão atende as necessidades do projeto. Por exemplo, pode haver uma função que permite editar páginas, editar posts de outros usuários, criar menus, configurar as categorias, mas não pode ter as permissões de atualização do sistema ou instalação de plugins. Nesse caso, pode-se alterar as capacidades (já iremos falar sobre) de uma função específica (editor, talvez), ou criar outra função, que é bem simples. Mas antes de falar sobre como criar novas funções, vou falar um pouco sobre as capacidades (do inglês capabilities). 

As capacidades são, segundo o Codex do projeto “Termos relacionados com a autenticação de usuários e controle de acesso. É uma aprovação de permissões no modo RBAC. Há cerca de trinta capacidades em WordPress.“.

Por exemplo, a permissão de criar um post é uma capacidade (edit_post), publicar o texto é outra (publish_post), e assim por diante. A lista de todas as capacidades pode ser encontrada no Codex [1].

 Depois dessa introdução, vamos ver na prática como fazer uma nova função (embora eu ache que a tradução mais adequada seria “papel”, pois função pode confundir com… as funções das linguagens de programação).

Em primeiro lugar, o Codex já avisa que essa função deve ser usada no momento de ativação de um plugin ou tema, já que a configuração fica salva no banco de dados [2]. Mas ela é bem simples de usar. Sua sintaxe é:

<?php add_role( $role, $display_name, $capabilities ); ?>

  • $role (String): o nome do papel;
  • $display_name (String): o nome que será exibido.
  • $capabilities (Array): uma lista de capacidades que o novo papel terá.

global $wp_roles;
$wp_roles->add_role( 'escritor', 'Escritor', array (
'upload_files' => true,
'read' => true,
'delete_posts' => true,
'delete_published_posts' => true,
'edit_posts' => true,
'edit_published_posts' => true,
'moderate_comments' => false,
'remove_users' => false,
));

Algumas considerações sobre essa função:

  • O “false” é para explicitar que determinado papel NÃO tem determinada capacidade, já que, caso a capacidade não conste nesta lista, o usuário não terá aquela capacidade.
  • add_role não tem uma função “update”. Isto é, se já houver aquele papel no banco de dados, a função é abortada, não modificando o papel. Portanto, se precisar modificar, durante o desenvolvimento, esta lista, é necessário chamar a função (viu aqui o problema com essa tradução? Estou falando de uma function, não de uma role) remove_role, ou a add_cap, que falarei sobre adiante.

A função remove_role é trivial, aceitando apenas um parâmetro, que é o nome da função que será deletada. [3]

<?php remove_role( 'escritor' ); ?>

Já a função add_cap [4] seta determinada capacidade para uma função ou usuário específico. Por exemplo:

$role = get_role( 'author' );

$role->add_cap( 'edit_others_posts' );

A principal desvantagem desta função é que permite acrescentar somente uma capacidade. Útil quando se precisa acrescentar uma ou duas, mas incômoda quando forem mais.

 Sim, existem diversos plugins que fazem esse trabalho para nós, com a vantagem de ter uma interface gráfica para selecionar as capacidades, setar os nomes dos papéis, mas é útil conhecer essas funções, quando estamos customizando o WordPress, diminuindo a dependência de plugins.

Referências:

[1] https://codex.wordpress.org/pt-br:Pap%C3%A9is_e_Capacidades

[2]https://codex.wordpress.org/Function_Reference/add_role

[3]https://codex.wordpress.org/Function_Reference/remove_role

[4] https://codex.wordpress.org/Function_Reference/add_cap

Ultimate Guide to Roles and Capabilities (recomendo este guia, em inglês).