Funções de usuários e Capacidades no WordPress – Parte 2: Funções interessantes
Este artigo é a parte 2 de 3 da série Funções de usuários e Capacidades do WordPress
- Funções de usuários e Capacidades do WordPress – Parte 1: O básico
- Funções de usuários e Capacidades no WordPress – Parte 2: Funções interessantes
- Funções de usuários e Capacidades no WordPress – Parte 3: Um exemplo prático
Esta série de três partes é um tutorial que visa cobrir bem as Funções de usuários e capacidades no WordPress. Esta séria irá cobrir a arquitetura e funcionamento das funções de usuários no WordPress; destacar as funções mais importantes para interação com usuários e gerenciamento de funções e capacidades; e no última parte, mostrar um exmplo prático que demonstra a utilidade da API do WordPress.
Introdução
Na primeira parte, postada pelo amigo Rudá Almeida, cobrimos apenas a teoria sobre usuários, funções e capacidades. Esta segunda parte irá focar mais em código e nas funções que o WordPress oferece para interagir com o sistema. Não iremos cobrir todas as funções que o WordPress tem para este fim, mas tentamos focar nas mais importantes e mais usadas.
Como o WordPress evolui e é atualizado constantemente, alterações nas funções podem acontecer, e por este motivo, para sua conveniência iremos sempre disponibilizar um link para a documentação oficial (conhecida como Codex) para você poder checar se algo mudou.
Gerenciando Usuários
Usuários no WordPress são diferentes de visitantes. Eles são pessoas que registraram uma conta com um nome de usuário único em seu site. Você pode habilitar o registro de novos usuários no seu site através do painel de administração, em Configurações -> Geral, e marcar a Opção “Qualquer pessoa pode se registrar”, e selecionar logo abaixo o nível de usuário que será dado automaticamente aos novos usuários registrados.
Nesta seção, iremos cobrir algumas funções interessantes para interagir com seus usuários registrados no WordPress. Sua nova instalação do WordPress deve ter pelo menos um usuário: aquele que configurou sua instalação. Nas versões antigas, ele tinha o nome de usuário admin, mas nas versões atuais, por motivos de segurança, cada usuário deve escolher na instalação o nome do usuário administrador (para diminuir as chances de um nome de usuário comum facilitar a tentativa de invasão ao seu site).
Criando, Atualizando e Apagando usuários.
O WordPress tem, é claro, uma interface visual para a criação, atualização e exclusão de usuários e você deve o utilizar na maioria das vezes. Entretanto, existem casos que você pode querer gerenciar isso através de programação. Por exemplo, na hora de importar novos usuários de um outro framework ou se você está criando um formulário personalizado de registro de usuários.
O WordPress tem quatro funções interessantes para realizar estas atividades:
Num primeiro momento, algumas dessas funções podem ser confusas, pois as 3 primeiras funções podem criar novos usuarios, tanto a “wp_insert_user” quanto a “wp_update_user” podem atualizar usuários já existentes. Mas existe uma razão para isso.
Existems duas maneiras de criar um novo usuário:
- Passando apenas as informações necessárias para criar um novo usuário (nome de usuário, email e senha). Neste caso, você deve usar a função
wp_create_user; - Passando um vetor com todas as informações do usuário. Neste caso, você deve usar a função
wp_insert_user. Isso lhe dá a capacidade de definir os dados do usuário para o usuário antes de adicioná-lo.
Para atualizar um usuário já existente, você deve usar a função wp_update_user. É possível usar a função wp_insert_user, entretanto, esta função não salva a senha do usuário however, essa função não faz o hash da senha do usuário e pode falhar. Por isso, é melhor usar a função certa para fazer tal trabalho 🙂
Abaixo, descrevemos um trecho de exemplo de uso para cada função. Você deve, no entanto, olhar o Codex se você estiver procurando por documentação mais detalhada.
Uso do wp_create_user
add_action( 'init', 'tpw_createuser' );
function tpw_createuser() {
// Dados do usuário
$user_name = 'nome_usuario;
$user_password = 'senha_novo_usuario';
$user_email = '[email protected]';
// Criar o usuário
$user_id = wp_create_user( $user_name, $user_password, $user_email );
// Checar se a função retornou um erro
if ( is_wp_error ($user_id) ) {
$user_id->get_error_message();
}
else {
// Usuário criado com sucesso
}
}
Uso do wp_insert_user
add_action('init','tpw_insertuser' );
function tpw_insertuser() {
// Preparar os dados do usuário
$user_data = array (
'user_login' => 'login_usuario,
'user_password' => 'senha_novo_usuario'
'user_email' => '[email protected]'
'role' => 'administrator'
);
// Criando o usuário
$user_id = wp_insert_user( $user_data );
// Checar se a função retornou um erro
if ( is_wp_error( $user_id ) ) {
$user_id->get_error_message();
}
else {
// Usuário criado com sucesso
}
}
Uso do wp_update_user
add_action( 'init', 'tpw_updateuser' );
function tpw_updateuser() {
// Preparar os dados do usuário
$user_data = array (
'user_id' => 3,
'description' => ' Nosso novo usuário criado'
);
// Atualizar a descrição do usuário
$user_id = wp_update_user( $user_data );
// Checar se a função retornou um erro
if ( is_wp_error( $user_id ) ) {
$user_id->get_error_message();
}
else {
// Usuário atualizado com sucesso
}
}
Uso do wp_delete_user
add_action( 'init', 'tpw_deleteuser' );
function tpw_deleteuser() {
if ( wp_delete_user( 3, 1 ) ) {
// Usuário removido com sucesso
}
}
Puxando uma listagem de usuários.
O WordPress oferece duas funções para recuperar a listagem de usuários, para que você não tenha que criar uma query e buscar no banco de dados. A primeira função é a “get_users_of_blog()”, que retorna um vetor com todos os usuários neste site (ou você pode passar o blog ID se você está usando uma instalação MultiSite). A segunda função, “get_users()”, returna uma lista de usuários baseado nos argumentos passados na função. Isso elimina a necessidade de criar query SQL para buscar no banco de dados.
As duas funções retornam um vetor com os dados dos usuários (Com exceção da get_users() onde você pode especificar o retorno de um campo específico) O objeto user será mais explicado nas próximas seções.
A função “get_users_of_blog()” está desatualizada, então você não deve mais usá-la, e deve utilizar a “get_users()” no seu lugar. O trecho abaixo é um exemplo de uso da função “get_users()“.
add_action( 'init', 'tpw_getusers' );
function tpw_getusers() {
// Critérios utilizados na query
$args = array (
'orderby' => 'url',
'order' => 'ASC');
// Pegar o vetor com usuários
$users = get_users( $args );
// Looping para mostrar o nome de usuário e sua URL
foreach( $users as $user) {
echo '<a href="' . $user->user_url . '">' . $user->user_url . '</a>';
}
}
Esta função aceita mais argumentos, e você pode achar uma lista completa destas opções no Codex.
blog_id– Apenas usada se você está usando Multisite.O valor padrão é o ID do blog atual (o que está rodando a função).role– Limita os usuários retornados por tipo de conta.include– Um vetor de IDs de usuários a serem incluidos no retorno da query.exclude– Um vetor de IDs de usuários a serem incluidos no retorno da query.
A classe WP_User
A classe WP_User permite acessar propriedades, funções e métodos relativos a um usuário específico. Para criar uma nova instância de classe, você precisa do ID do usuário ou do nome de usuário; e se você está numa instalação MultiSite, você vai precisar do ID do blog também.
Você pode inicializar esta classe para um usuário em particular, e despejar o conteúdo de classe. Isso irá exibir apenas as propriedades, mas ainda é útil quando você quer ler a classe do usuário.
add_action( 'init', 'tpw_wpuserclass' );
function tpw_wpuserclass() {
$user = new WP_User( 1 );
var_dump( $user );
}
Vejamos a seguir uma lista de propriedades e métodos da classe WP_User:
Propriedades do WP_User
data(Objeto – with dados de usuários como nome de usuário, senha ,URL, etc)ID(Integer – ID do usuário)caps(vetor)roles(vetor – Funções habilitadas para o usuário)cap_key(String)allcaps(vetor – Todas as capacidades que o usuário tem)filter(Null)
Métodos Públicos do WP_User
get_role_caps()– Seta as funções e capacidades.add_role()– Adiciona função para o usuário.remove_role()– Remove função do usuário.set_role()– Seta uma função para o usuário. Isto irá remover todos as funções previamente setadas.add_cap()– Adiciona capacidades para o usuário.remove_cap()– Remove capacidades do usuário.remove_all_caps()Remove todas as capacidades do usuário.has_cap()Checa se o usuário tem a capacidade ou função citada.
Meta dados dos Usuários
Como dito no artigo anterior, meta dados de usuários são dados sobre os usuários salvos na tabela wp_usermeta. São salvos como chaves/pares de valores, e o meta valor pode ser qualquer tipo de dado. O par não é necessáriamente único, você pode guardar múltiplos pares com a mesma chave.
Adicionando meta-dados de usuários
A função add_user_meta() adiciona, como o nome diz, novos meta-dados de usuários. A função retorna verdadeiro se os dados são adicionados com sucesso, e falso quando falha. Como mencionado anteriormente, é possível adicionar vários meta valores com a mesma chave. Se você quer criar meta keys únicos, sete o quarto argumento como verdadeiro.
add_action('init', 'tpw_addusermeta');
function tpw_addusermeta() {
// Adiciona múltiplos meta valores com a mesma meta key
add_user_meta( 1, 'bookmarks', 'https://site1.com', false );
add_user_meta( 1, 'bookmarks', 'https://site2.com', false );
add_user_meta( 1, 'bookmarks', 'https://site3.com', false );
}
Recuperando Meta-Dados dos usuários
A função get_user_meta() returna o meta valor baseado no ID do usuário e meta key passado.
add_action('init', 'tpw_getusermeta');
function tpw_getusermeta() {
// Recuperar os bookmarks do usuário
$bookmarks = get_user_meta( 1, 'bookmarks', false );
echo '<ul>';
foreach ( $bookmarks as $bookmark ) {
echo '<li><a href="' . $bookmark . '">' . $bookmark . '</a></li>';
}
echo '</ul>';
}
Atualizando os meta-dados do usuário
A função update_user_meta() atualiza um único meta valor. Se tiverem vários valores na mesma meta key, e nenhum meta valor anterior for especificado, então o novo valor irá sobrescrever os meta valores anteriores.
add_action('init', 'tpw_updateusermeta');
function tpw_updateusermeta() {
// Atualiza o bookmark do usuário
update_user_meta( 1, 'bookmarks', 'https://site2.com', 'https://site2.com' );
}
Removendo os meta-dados do usuário
A função delete_user_data() removes um único ou todos os meta keys/pares para um dado meta key. Se você quer remover um valor único, então você deve especificar o terceiro argumento.
add_action('init', 'tpw_removeusermeta');
function tpw_removeusermeta() {
// Atualizar os bookmarks do usuário
delete_user_meta( 1, 'bookmarks', 'https://site2.com' );
}
Gerenciando Funções e Capacidades
Criando e Removendo Funções
As funções do WordPress são extensivas. Você pode adicionar e remover funções. Adicionar uma função é bem simple, e você precisa apenas do slug, nome a ser exibido e as capacidades que a função tem.
add_action( 'init', 'tpw_addrole' );
function tpw_addrole() {
add_role( 'uploader', 'Uploader', array('upload_files') );
add_role( 'link_manager', 'Link Manager', array('manage_links') );
}
Se você checar uma página de perfil de usuário ( Usuários ->Seu Perfil ), Você verá que os novos níveis de usuários que você acabou de adicionar estão disponíveis, e são mostrados com o nome que você setou.
É importante mencionar que a criação de nível de usuário só precisa ser feite uma vez. Então, se você está criando um gancho para a ação “init” como no código acima, você está recriando o papel cada vez que o código roda. Isso está longe do ideal, pois na prática você deve criá-lo apens uma vez. Você deve ativar tal gancho na ativação do plugin e ter a certeza de o remover quando o plugin for desativado.
Remoção de papéis é bastante simples também. Você só precisa do nome do papel.
add_action( 'init', 'tpw_removerole' );
function tpw_removerole() {
remove_role( 'uploader' );
remove_role( 'link_manager' );
}
Adicionando Capacidades e Funções
Da mesma forma que os usuários, os papéis têm uma classe especial: WP_Role. No entanto, a inicialização desta classe requer tanto o nome da função e também as capacidades de papel, o que não é tão úsual.
O WordPress oferece uma outra função get_role (), que exige apenas o nome da função e inicializa a classe para você.
add_action('init', 'tpw_getrole');
function tpw_getrole() {
$role = get_role('editor');
var_dump($role);
}
O objeto retornado tem duas propriedades, e três métodos.
Propriedades do WP_Role
capabilitiesUm vetor com as capacidades que o papel tem.nameNome do papel/função.
Métodos do WP_Role
add_cap()Adicionar a capacidade ao objetohas_cap()Verificar se possui tal capacidaderemove_cap()Remover a capacidade
Checando Permissões
Funções e capacidades estão ai para serem usadas, e você deve aplicá-las em seu plugin ou tema, verificando-os antes de executar um código específico para um tipo de usuário. Lembre-se que você deve checar sempre as capacidades, não os níveis de usuário, pois ver se um usuário tem o nível ‘editor não lhe garante que um determinado usuário tem a capacidade padrão que o WordPress determina pois elas podem ter sido alteradas por você ou por algum outro plugin.
O WordPress tem 3 funções para checar permisões, que são permutáveis em algum grau.
current_user_can() verifica se o usuário atual tem a capacidade especificada. Ele também aceita um post ou objeto para verificar se há meta-capacidades.
user_can() funciona da mesma forma, mas você pode especificar o ID do usuário. Ele não verifica meta-capacidades, no entanto. Por isso, é um pouco ruim se você quiser verificar se há uma capacidade para um usuário diferente do usuário atual. Para isso, você pode usar o author_can(), função que verifica se um post autor pode executar uma tarefa específica com base em um recurso e pós-ID
// checa se o autor do primeiro post pode publicar posts
if ( author_can( 1, 'publish_posts') ) {
publish_post_function(); // publicar o post
}
else {
echo "Você não tem privilégios suficientes para publicar um post";
}
Conclusão
Nesta parte, tentamos cobrir várias funções que o WordPress tem para estes fins, e ainda explicar o usu de cada uma. Agora, você deve estar habilitado para criar plugin ou temas que usem as capacidades de usuários da forma correta. No próximo artigo desta série, iremos mostrar como cria um plugin que usa isso tudo citado.
Fonte: O texto acima é uma tradução livre do artigo escrito por Abid Omar e publicado originalmente no site WP Tuts
