Desenvolvimento de Plugins WordPress para Principiantes

Introdução ao desenvolvimento de plugins WordPress

Os plugins extensíveis do WordPress são complementos modulares que ampliam a funcionalidade do WordPress sem modificar o código do core. Com mais de 60.000 plugins no repositório oficial do WordPress, o ecossistema de plugins é uma das maiores razões pelas quais o WordPress é o CMS mais utilizado do mundo. Desenvolver os seus próprios plugins dá-lhe controlo total sobre a funcionalidade do site e permite-lhe criar soluções feitas exatamente à medida das necessidades dos seus clientes ou do seu próprio negócio.

Para começar a desenvolver um plugin WordPress, precisa de um ambiente de desenvolvimento local ou de alojamento com instalação WordPress, conhecimentos de PHP de nível básico a intermédio e compreensão da arquitetura do WordPress, especialmente do sistema de hooks. Ferramentas como o Local by Flywheel, o XAMPP ou o Docker facilitam a configuração de um ambiente local para desenvolver e testar plugins antes de os publicar em produção.

Estrutura de um plugin WordPress

Todos os plugins WordPress começam a partir de um único ficheiro PHP com um comentário especial no cabeçalho que indica ao WordPress que se trata de um plugin. Este comentário contém o nome do plugin, a descrição, a versão, o autor e outros metadados. O WordPress analisa a pasta wp-content/plugins e lê estes cabeçalhos para apresentar a lista de plugins disponíveis no painel de administração.

Estrutura mínima de um plugin

O plugin mais simples é um ficheiro PHP na pasta wp-content/plugins com um cabeçalho adequado. No entanto, para um plugin mais sério, recomenda-se a organização numa pasta dedicada com o ficheiro principal, a pasta includes para classes auxiliares, a pasta admin para páginas de administração, a pasta public para o código de frontend e a pasta assets para ficheiros CSS e JavaScript.

• plugin-name/plugin-name.php - ficheiro principal do plugin com cabeçalho e inicialização
• plugin-name/includes/ - classes PHP e funções auxiliares
• plugin-name/admin/ - páginas de administração, definições, metaboxes
• plugin-name/public/ - funcionalidade de frontend e templates
• plugin-name/assets/css/ - estilos CSS para admin e frontend
• plugin-name/assets/js/ - ficheiros JavaScript
• plugin-name/languages/ - ficheiros de localização e tradução
• plugin-name/templates/ - templates HTML que o tema pode substituir

Use namespaces ou prefixos para todas as funções. Consulte o guia de segurança do site para dicas adicionais e classes que evitam conflitos com outros plugins. Por exemplo, em vez de uma função genérica get_settings(), use beo_plugin_get_settings() ou, melhor, um namespace PHP BeoPlugin e classes. Isto é crítico, pois o WordPress carrega todos os plugins ativos no mesmo escopo PHP e os conflitos de nomes levam a erros fatais.

Sistema de hooks do WordPress

O sistema de hooks é o coração da arquitetura do WordPress e compreender os hooks é absolutamente essencial para o desenvolvimento de plugins. O WordPress define centenas de hooks em pontos-chave do processo de execução do código, e os plugins ligam-se a estes para executar o seu próprio código no momento certo. Existem dois tipos de hooks: actions e filters.

Actions

As actions são hooks que lhe permitem executar código num ponto específico do processo do WordPress. Por exemplo, a action init dispara depois de o WordPress terminar o carregamento mas antes de enviar qualquer output, wp_enqueue_scripts dispara quando é preciso adicionar ficheiros CSS e JS, e save_post dispara quando um post é guardado. Use a função add_action() para registar a sua função callback num determinado action hook.

Filters

Os filters são hooks que lhe permitem modificar dados antes de o WordPress os utilizar ou apresentar. Uma função callback de filter recebe um valor, modifica-o e devolve a versão modificada. Por exemplo, o filter the_content permite-lhe alterar o conteúdo do post antes da apresentação, the_title altera o título e o filter wp_mail permite modificar mensagens de email antes do envio. Use add_filter() para registar callbacks de filter.

• add_action('hook_name', 'callback', priority, args) - regista uma função num action hook
• add_filter('hook_name', 'callback', priority, args) - regista uma função num filter hook
• do_action('custom_hook') - cria o seu próprio action hook que outros plugins podem usar
• apply_filters('custom_filter', $value) - cria o seu próprio filter hook
• remove_action() / remove_filter() - remove uma função registada anteriormente

O parâmetro priority (predefinição 10) determina a ordem de execução quando estão registadas várias funções no mesmo hook. Um número mais baixo significa execução mais cedo. Isto é útil quando quer que o seu código seja executado antes ou depois do código de outro plugin no mesmo hook. Defina sempre explicitamente a priority se a ordem de execução for importante, pois o valor predefinido pode levar a resultados imprevisíveis.

Criar páginas de administração

A maioria dos plugins requer páginas de administração para configurar definições. O WordPress disponibiliza a Settings API para criar páginas de definições que se integram com o painel de administração do WordPress. Use add_menu_page() para adicionar um item de menu principal ou add_submenu_page() para adicionar uma subpágina sob um item de menu existente.

Settings API

A Settings API do WordPress automatiza o armazenamento e a validação das definições utilizando a tabela de options do WordPress. Regista as definições com register_setting(), define secções com add_settings_section() e campos com add_settings_field(). O WordPress gera depois automaticamente o formulário, armazena os dados e aplica a sanitização. Esta é uma abordagem mais segura do que o tratamento manual de pedidos POST, pois a Settings API adiciona automaticamente verificação de nonce e verificação de permissões do utilizador.

Para interfaces de administração mais complexas, pode usar páginas de administração personalizadas com o seu próprio HTML e JavaScript em vez da Settings API. Nesse caso, use os hooks wp_ajax_ para as chamadas AJAX e certifique-se de adicionar verificação de nonce com wp_nonce_field() e check_admin_referer() para proteção contra ataques CSRF. Verifique também as permissões do utilizador com current_user_can() no início de cada página de administração e handler AJAX.

Exemplo de menu de administração

Na prática, criar uma página de administração requer dois passos. Primeiro, registe o item de menu no hook admin_menu usando add_menu_page com parâmetros para o título da página, o título do menu, a permissão necessária (normalmente manage_options para administradores), o slug da página, a função callback que renderiza o HTML e, opcionalmente, um ícone. Depois, na função callback, gere a página HTML com um formulário usando settings_fields() e do_settings_sections() para a renderização automática das definições registadas.

Criar shortcodes

Os shortcodes permitem aos utilizadores incorporar a funcionalidade do seu plugin diretamente no conteúdo de posts e páginas, usando etiquetas curtas entre parênteses retos. Registe um shortcode com a função add_shortcode(), que recebe o nome do shortcode e a função callback. O callback recebe os atributos que o utilizador especificou, o conteúdo entre as etiquetas de abertura e fecho e o próprio nome do shortcode.

Exemplo de implementação

Imagine criar um plugin para apresentar membros da equipa. O shortcode [team_member name="Marko" role="Developer" photo="url"] apresentaria um cartão estilizado com a fotografia, o nome e a função do membro da equipa. A função callback recebe o array $atts, usa shortcode_atts() para definir valores predefinidos e devolve uma string HTML com a apresentação formatada. Nunca use echo num callback de shortcode, mas devolva sempre uma string, pois o echo perturba a ordem de apresentação do conteúdo na página.

• Shortcode auto-fechado - [button text="Click" url="/link"] - sem conteúdo no meio
• Shortcode envolvente - [highlight]texto importante[/highlight] - tem conteúdo entre as etiquetas
• Shortcodes aninhados - do_shortcode($content) no callback para suporte de aninhamento

Ativação, desativação e desinstalação

O WordPress disponibiliza três hooks para os eventos do ciclo de vida do plugin. register_activation_hook() é chamado quando o utilizador ativa o plugin e aí normalmente cria tabelas na base de dados, define definições predefinidas e regista tarefas cron. register_deactivation_hook() é chamado na desativação e aí limpa temporizadores e dados temporários, mas deixa os dados, pois o utilizador pode reativar o plugin.

Para a eliminação permanente de dados na desinstalação, use register_uninstall_hook() ou o ficheiro uninstall.php na pasta raiz do plugin. Aqui elimina tabelas da base de dados, remove options da tabela wp_options e limpa todos os dados que o plugin criou. Implemente sempre estes hooks, pois um plugin que deixa dados na base de dados após a desinstalação é uma má prática que ocupa recursos desnecessariamente e polui a base de dados.

Segurança e boas práticas

A segurança é crítica no desenvolvimento de plugins, pois um plugin vulnerável pode comprometer toda a instalação WordPress e todos os sites no mesmo servidor. Valide e sanitize sempre todos os dados introduzidos pelo utilizador com sanitize_text_field(), absint(), esc_url() e outras funções de sanitização do WordPress. Use prepared statements com $wpdb->prepare() em todas as consultas à base de dados para prevenir ataques de SQL injection.

• Verificação de nonce - wp_nonce_field() e wp_verify_nonce() para proteção contra CSRF
• Verificações de capability - current_user_can() antes de cada ação privilegiada
• Escape de output - esc_html(), esc_attr(), esc_url() para todos os dados dinâmicos em HTML
• Prepared statements - $wpdb->prepare() para todas as consultas com dados do utilizador
• Validação de upload de ficheiros - verificar o tipo MIME, o tamanho do ficheiro e a extensão
• Proteção contra acesso direto - defined('ABSPATH') || exit; no início de cada ficheiro PHP

Siga os WordPress Coding Standards para um código consistente e legível. Use o sistema de internacionalização do WordPress com as funções __() e _e() para todas as strings que o utilizador vê, para que o seu plugin possa ser traduzido para outras línguas. Teste o plugin com o WP_DEBUG ativado para detetar todos os erros e avisos antes de publicar. Considere escrever testes PHPUnit para a lógica crítica do plugin, pois os testes automatizados previnem regressões durante as atualizações.