Funções e capacidades do WordPress: O guia completo (2026)

A maior falha de segurança na maioria dos sites WordPress não é uma vulnerabilidade de plugin. É dar ao cliente acesso de “Administrador” quando ele apenas precisa de editar posts.

Ou pior, dar a um “Estagiário” a capacidade de mudar temas (switch_themes).

O WordPress tem um poderoso sistema de Controlo de Acesso (ACL) integrado. Chama-se Funções e Capacidades (Roles & Capabilities). Neste guia, vamos além da função padrão de “Editor” e aprender a arquitetar permissões seguras.

1. Conceitos: Função (role) vs capacidade (capability)

• Capacidade (Cap): Uma permissão específica para fazer uma coisa.
  • Exemplo: edit_posts (editar posts), publish_pages (publicar páginas), install_plugins (instalar plugins).
• Função (Role): Uma coleção de capacidades.
  • Exemplo: Editor = edit_posts + publish_posts + manage_categories (mas NÃO install_plugins).

Regra de Ouro: Verifique sempre por Capacidades, nunca por Funções.

// ❌ ERRADO
if ( current_user_can( 'administrator' ) ) { ... }

// ✅ CERTO
if ( current_user_can( 'manage_options' ) ) { ... }

2. Criar uma função personalizada

Digamos que tem um “Gerente de Loja” que precisa de gerir Produtos, mas não deve tocar no seu Tema ou Plugins.

function wppoland_add_store_manager_role() {
    add_role(
        'store_manager',
        'Gerente de Loja',
        [
            'read'         => true,
            'edit_posts'   => true,
            'upload_files' => true,
            'manage_woocommerce' => true, // Capacidade personalizada
        ]
    );
}
// Execute APENAS UMA VEZ (ex: na ativação do plugin)
// add_action( 'init', 'wppoland_add_store_manager_role' );

Importante: As funções são armazenadas na base de dados (wp_options > wp_user_roles). Não precisa de executar add_role em cada carregamento de página. Execute uma vez na implementação.

3. Adicionar capacidades a funções existentes

Às vezes, quer apenas permitir que o “Editor” edite Menus (o que não podem fazer por padrão).

function wppoland_upgrade_editor() {
    $role = get_role( 'editor' );
    if ( $role ) {
        $role->add_cap( 'edit_theme_options' ); // Permite edição de Menus e Widgets
    }
}
// Execute uma vez

4. Recuperação de desastres: Redefinir funções

Se um plugin estragou a sua base de dados ou apagou acidentalmente a função de ‘Administrador’ (acontece!), precisa de um hard reset.

Este script restaura a arquitetura padrão do WordPress.

function wppoland_reset_roles() {
    if ( ! isset( $_GET['reset_roles_secret_key'] ) ) return;

    require_once( ABSPATH . 'wp-admin/includes/schema.php' );
    populate_roles();
    
    echo "Funções Redefinidas com Sucesso.";
    exit;
}
add_action( 'init', 'wppoland_reset_roles' );

5. Melhores práticas de segurança 2026

A. Não use o nome de utilizador ‘admin’

Ataques de força bruta visam o ID de utilizador 1 ou o nome de utilizador ‘admin’.

B. Map meta capabilities

Ao usar Custom Post Types, não use apenas edit_posts. Mapeie caps granulares:

register_post_type( 'book', [
    'capability_type' => 'book',
    'map_meta_cap'    => true, // Chave para controlo granular
] );

Agora pode dar a um utilizador edit_books sem lhe dar edit_posts.

Resumo

• Princípio do Privilégio Mínimo: Dê aos utilizadores apenas o que eles precisam.
• Funções Personalizadas: Melhor do que hackear a função de ‘Editor’.
• Base de Dados: As funções vivem na BD, não no código. As mudanças persistem.

Dominar capacidades específicas é a diferença entre um site seguro e um hackeado.