Desenvolvimento de plugins para WordPress: Do básico ao avançado: Crie o seu primeiro plugin funcional

Por que aprender o desenvolvimento de plugins para o WordPress?

O WordPress, como o sistema de gestão de conteúdo mais popular mundialmente, deve sua grande capacidade de expansão aos inúmeros plugins disponíveis. Aprender a desenvolver plugins não só permite que você personalize as funcionalidades do site de acordo com suas necessidades, mas também ajuda a compreender profundamente a arquitetura central do WordPress, melhorando seu nível técnico. Além disso, você pode transformar suas ideias em produtos reais e publicáveis. Ao desenvolver seus próprios plugins, você tem total controle sobre a qualidade do código, garante a segurança do site e evita problemas de compatibilidade que podem surgir com o uso de plugins de terceiros.

Um plugin básico para o WordPress é, essencialmente, um ou mais arquivos PHP localizados em um diretório específico. Esse plugin interage com o sistema principal do WordPress através da API abrangente fornecida pelo próprio WordPress (como ganchos de ação, ganchos de filtro, códigos curtos, widgets, etc.). Compreender esse mecanismo é um pré-requisito para o desenvolvimento bem-sucedido de qualquer plugin.

Preparar o ambiente de desenvolvimento e a infraestrutura básica

Antes de escrever a primeira linha de código, é essencial criar um bom ambiente de desenvolvimento. Você precisará de um servidor local (como XAMPP, Local by Flywheel ou DevKinsta), um editor de código (como VS Code ou PhpStorm), e uma instalação do WordPress para testes.

Leitura recomendada Guia Definitivo para o Desenvolvimento de Plugins para WordPress: Domine os Princípios Fundamentais e Projeto Práticos。

A entrada para o plugin é um arquivo PHP principal. As comentários no início desse arquivo são cruciais para que o WordPress reconheça o plugin. Vamos primeiro criar a estrutura básica do plugin.

Criar o arquivo principal do plugin

O arquivo principal de um plugin geralmente tem o mesmo nome que o plugin. Por exemplo, se criarmos um plugin chamado “Meu Primeiro Plugin”, o seu arquivo principal pode ser nomeado…my-first-plugin.phpEste arquivo deve ser colocado em…/wp-content/plugins/my-first-plugin/No diretório.

O cabeçalho do arquivo deve conter as anotações de informações padrão do plugin. Aqui está um exemplo básico:

<?php
/**
 * Plugin Name:       我的第一个插件
 * Plugin URI:        https://example.com/my-first-plugin
 * Description:       这是一个用于学习WordPress插件开发的功能插件示例。
 * Version:           1.0.0
 * Author:            你的名字
 * Author URI:        https://example.com
 * License:           GPL v2 or later
 * Text Domain:       my-first-plugin
 * Domain Path:       /languages
 */

Após salvar o arquivo, acesse a página “Plugins” no painel administrativo do WordPress. Você deve ver o novo plugin na lista de plugins e poderá ativá-lo. No momento, ele não possui nenhuma funcionalidade, mas a estrutura básica já foi criada.

Estabelecer a estrutura básica do diretório do plugin

Um plugin com estrutura clara é benéfico para a manutenção a longo prazo. Sugere-se a criação dos seguintes diretórios:
* /assets/É usado para armazenar recursos estáticos, como CSS, JavaScript e imagens.
* /includes/É usado para armazenar os arquivos de classes PHP centrais e os arquivos de funções.
* /languages/Usado para armazenar arquivos de tradução internacionalizados (.po/.mo).

Leitura recomendada O essencial do princípio do Tailwind CSS: descobrindo o mecanismo de funcionamento do framework de CSS atomizado que prioriza a praticidade。

Arquivo principalmy-first-plugin.phpDeveria ser responsável apenas pelo trabalho de inicialização dos plugins, como a definição de constantes, a inclusão de outros arquivos e o registro de funções de interação (hook functions).

Implementar as funcionalidades principais: criar menus de gerenciamento e páginas.

Uma função comum de um plugin é adicionar uma página de menu de gerenciamento no painel administrativo do WordPress. Vamos implementar isso utilizando a “API de Páginas de Menu” do WordPress.

Adicionar um menu principal no backend.

Nós precisamos usar…add_menu_page()Função. Esta função é normalmente utilizada emadmin_menuEste gancho de ação é chamado quando é acionado. Adicionamos o seguinte código no arquivo principal:

// 定义在管理员菜单初始化时执行的功能
function mfp_add_admin_menu() {
    add_menu_page(
        '我的插件设置',         // 页面标题
        '我的插件',            // 菜单标题
        'manage_options',      // 所需权限
        'my-first-plugin',     // 菜单slug
        'mfp_display_settings_page', // 用于显示页面内容的回调函数
        'dashicons-admin-generic', // 菜单图标（Dashicon）
        6                      // 菜单位置
    );
}
// 将函数挂载到 `admin_menu` 钩子上
add_action('admin_menu', 'mfp_add_admin_menu');

Criar o conteúdo exibido na página de configurações.

No código acima,mfp_display_settings_pageÉ uma função de callback responsável por gerar o conteúdo HTML da página de configurações. Precisamos definir essa função:

// 设置页面的显示内容
function mfp_display_settings_page() {
    // 检查用户权限
    if (!current_user_can('manage_options')) {
        wp_die(__('你没有权限访问此页面。'));
    }
    ?>
    <div class="wrap">
        <h1><?php echo esc_html(get_admin_page_title()); ?></h1>
        <form action="/pt/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            // 输出设置字段和安全nonce字段
            settings_fields('mfp_options_group'); // 设置组的名称
            do_settings_sections('my-first-plugin'); // 页面slug
            submit_button('保存设置');
            ?>
        <input type="hidden" name="trp-form-language" value="pt"/></form>
    </div>
    &lt;?php
}

Este código cria uma estrutura padrão para uma página de configurações no WordPress, na qual são utilizados vários elementos internos.settings_fields()edo_settings_sections()Função… Isso significa que utilizaremos a API do WordPress Settings para gerenciar nossas opções, o que é a maneira mais segura e padronizada de fazer.

Use a API de Configurações (Settings API) para gerenciar as opções dos plugins.

Tratar diretamente.$_POSTExistem riscos de segurança nos dados. O WordPress Settings API cuida da validação, segurança e armazenamento dos dados para nós, sendo a metodologia preferida para a configuração de plugins.

Leitura recomendada Guia definitivo do plugin WooCommerce: construir um site independente de comércio eletrónico transfronteiriço profissional a partir do zero.。

Configurações de registro, campos e seções

Nós precisamos de…admin_initInicializamos nossas configurações no “gancho” (hook). Primeiramente, use…register_setting()Registre uma opção de configuração.

function mfp_register_settings() {
    // 注册一个设置：`mfp_options` 是存储在`wp_options`表中的键名
    register_setting(
        'mfp_options_group', // 设置组名，需与`settings_fields()`参数一致
        'mfp_options',       // 选项名
        'mfp_sanitize_options' // 可选：数据清洗回调函数
    );

// 添加一个设置章节
    add_settings_section(
        'mfp_main_section',                // 章节ID
        '主要设置',                         // 章节标题
        'mfp_main_section_callback',       // 章节介绍的回调函数
        'my-first-plugin'                  // 所属页面slug
    );

// 在章节中添加一个文本字段
    add_settings_field(
        'mfp_text_field',                  // 字段ID
        '示例文本',                         // 字段标签
        'mfp_text_field_callback',         // 用于渲染字段HTML的回调函数
        'my-first-plugin',                 // 所属页面slug
        'mfp_main_section'                 // 所属章节ID
    );
}
add_action('admin_init', 'mfp_register_settings');

Definir as funções de renderização e limpeza dos campos

Agora, precisamos definir cada uma das funções de callback mencionadas acima, que serão usadas para gerar o HTML dos campos de saída e para limpar os dados.

// 主章节的描述文本
function mfp_main_section_callback() {
    echo '<p>Esta é a principal área de configuração dos plugins.</p>';
}

// 文本字段的HTML输出
function mfp_text_field_callback() {
    // 从数据库获取现有值
    $options = get_option('mfp_options');
    $value = $options['mfp_text_field'] ?? ''; // PHP 7.0+ 空合并运算符
    echo '<input type="text" name="mfp_options[mfp_text_field]" value="' . esc_attr($value) . '" class="regular-text">';
}

// 数据清洗函数（可选但推荐）
function mfp_sanitize_options($input) {
    $sanitized_input = [];
    if (isset($input['mfp_text_field'])) {
        // 对文本字段进行基本的清洗，如去除标签
        $sanitized_input['mfp_text_field'] = sanitize_text_field($input['mfp_text_field']);
    }
    return $sanitized_input;
}

Até este ponto, um plugin completo, com uma página de configurações de segurança, foi desenvolvido. Após ativar o plugin, você poderá ver o menu “Meus Plugins” no painel administrativo do WordPress. Ao clicar nele, poderá configurar e salvar uma opção de texto. Todos os dados são armazenados de forma segura através da API do WordPress.wp_optionsNa tabela.

Adicionar funcionalidades front-end ao plugin: criar códigos curtos.

As funcionalidades do backend são fundamentais, mas os plugins também costumam afetar a parte frontal ( frontend) do site. Criar códigos encurtados (shortcodes) é uma ótima maneira de integrar as funcionalidades dos plugins em artigos, páginas ou ferramentas adicionais do site.

Registre um código curto e simples.

Nós vamos registrar um nome chamado…[my_greeting]Este é o código abreviado usado para exibir uma saudação no frontend.add_shortcode()Função.

Adicione no arquivo principal ou em um arquivo de funcionalidades específico:

// 注册短代码
function mfp_greeting_shortcode($atts, $content = null) {
    // 使用shortcode_atts设置默认属性并合并用户输入
    $atts = shortcode_atts(
        array(
            'name' => '访客', // 默认值
        ),
        $atts,
        'my_greeting' // 短代码名称
    );

// 获取插件选项中存储的文本
    $options = get_option('mfp_options');
    $custom_text = $options['mfp_text_field'] ?? '';

// 构造输出
    $output = '<div class="mfp-greeting">'$output .= '<p>Olá, '. esc_html($atts['name']) . '! Bem-vindo(a) ao nosso site.</p>';
    if (!empty($custom_text)) {
        $output .= '<p><strong>Mensagem personalizada:</strong>'`. esc_html($custom_text)`.'</p>'$output = '</div>';

// 返回输出内容，而不是直接echo
    return $output;
}
add_shortcode('my_greeting', 'mfp_greeting_shortcode');

Agora, os usuários podem inserir conteúdo no editor de artigos.[my_greeting name="张三"]O front-end irá renderizar uma mensagem de saudação personalizada, e se o “texto de exemplo” for definido no back-end, ele também será exibido. Esse método conecta de forma eficaz as configurações do back-end com a exibição no front-end.

resumos

Através dos passos acima, completamos um plugin para o WordPress com funcionalidades completas. Começamos do zero, criamos os arquivos e a estrutura básica do plugin, e utilizamos…add_menu_page()Com a API de Configurações, foi criada uma página de configurações segura no backend, e isso foi feito através de…add_shortcode()A funcionalidade de exibição no lado front-end foi implementada. Este processo abrangeu o fluxo central do desenvolvimento de plugins: planejamento, inicialização, integração com APIs do backend, processamento de dados e fornecimento de interfaces para o lado front-end.

Após dominar esses conceitos básicos, você poderá explorar temas mais avançados, como a criação de tipos de artigos personalizados, metadados (Meta Boxes), tabelas de banco de dados personalizadas, endpoints de API REST, tratamento de dados via AJAX e a internacionalização de plugins. Lembre-se de que seguir os padrões de codificação e as melhores práticas do WordPress é essencial para desenvolver plugins de alta qualidade e fáceis de manter.

Perguntas frequentes Perguntas frequentes

Quais conhecimentos em PHP são essenciais para o desenvolvimento de plugins?

É necessário dominar pelo menos a gramática básica do PHP, incluindo variáveis, arrays, funções, condições de avaliação e ciclos. O conhecimento de Programação Orientada a Objetos (POO) é de grande ajuda na criação de plugins de tamanho médio e grande. Além disso, é essencial entender como o WordPress carrega os plugins, bem como como usar variáveis e funções globais de forma segura.

Como depurar um plugin para WordPress que você mesmo desenvolveu?

Primeiro, certifique-se de que…wp-config.phpO ficheiro foi aberto.WP_DEBUGeWP_DEBUG_LOGDessa forma, as mensagens de erro serão registradas no arquivo de log. Em segundo lugar, é possível utilizar…error_log()A função exibe informações de depuração. Para lógicas complexas, é possível utilizar ferramentas de depuração profissionais, como o Xdebug, para executar o código passo a passo.

Como garantir a segurança de um plugin ao desenvolvê-lo?

Sempre verifique e limpe as entradas dos usuários. Utilize as funções integradas ao WordPress, como…esc_html(), esc_attr(), sanitize_text_field()ewp_kses()Vamos processar a saída. Utilize um método que não seja baseado em “CE”.wp_nonce_field()Isso é feito para prevenir a falsificação de solicitações entre sites (Cross-Site Request Forgery – CSRF). Para operações no banco de dados, utiliza-se…$wpdbOs métodos fornecidos pela classe, ou seu uso.prepare()Frases para prevenir injeções SQL.

Os plugins devem ser desenvolvidos localmente ou em servidores online?

É fortemente recomendado que o trabalho de desenvolvimento principal seja realizado em um ambiente local (como Local ou XAMPP). Os ambientes locais têm resposta rápida, não são afetados pela rede, e permitem que você teste e faça alterações à vontade sem prejudicar o site online. Após a conclusão das principais funcionalidades, o código deve ser deployado para um ambiente de teste online para realizar testes de compatibilidade finais.

Como publicar o seu próprio plugin no diretório oficial do WordPress?

Você precisa acessar o WordPress.org, registrar uma conta de desenvolvedor e enviar o código do seu plugin através do Subversion (SVN). O plugin deve atender aos padrões oficiais de código e às exigências de estrutura de diretórios, incluindo todos os elementos necessários.readme.txtArquivo. Após a aprovação da revisão, os usuários de todo o mundo poderão pesquisar e instalar seu plugin diretamente no backend.