Guia de introdução ao desenvolvimento de plugins do WordPress: crie o seu primeiro plugin personalizado do zero.

Preparação do ambiente de desenvolvimento de plugins para o WordPress

Antes de começar a escrever o código, você precisa de um ambiente de desenvolvimento adequado. Isso não só melhora a sua eficiência de desenvolvimento, mas também ajuda a depurar e testar os plugins com mais facilidade. Primeiramente, você deve configurar um ambiente de execução do WordPress no seu computador local. Você pode optar por usar ambientes de desenvolvimento integrados, como XAMPP, MAMP ou Local by Flywheel, que permitem instalar rapidamente o PHP, o MySQL e os servidores Apache/Nginx. Para os arquivos do núcleo do WordPress, é recomendado baixar e instalar a versão mais recente e estável do site oficial.

Assegure-se de que a sua versão do PHP atenda aos requisitos mínimos do WordPress e ative a funcionalidade de relatórios de erros, o que é essencial para a depuração. Você pode fazer isso…wp-config.phpAdicione o seguinte código ao arquivo para ativar o modo de depuração:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true); // 将错误记录到 /wp-content/debug.log
define('WP_DEBUG_DISPLAY', false); // 不在页面上显示错误

Além disso, um editor de código poderoso é essencial, como o Visual Studio Code, o PhpStorm ou o Sublime Text. Esses editores geralmente oferecem realce de sintaxe, sugestões de código e integração com sistemas de controle de versão, o que melhora significativamente a experiência de programação. Por fim, recomenda-se instalar ferramentas de desenvolvimento no navegador e considerar o uso de extensões desenvolvidas especificamente para o WordPress, para facilitar a verificação de funções („hooks“), a consulta ao banco de dados e o monitoramento do desempenho do site.

Leitura recomendada Guia de Iniciação para Desenvolvimento de Plugins para WordPress: Criando seu Primeiro Módulo de Funcionalidade do Zero。

Crie o seu primeiro arquivo de plugin.

A forma mais básica de um plugin para o WordPress é um arquivo PHP. Todos os plugins são armazenados em um determinado local no sistema do WordPress./wp-content/plugins/Dentro do diretório, cada plugin pode ser um arquivo PHP independente ou uma pasta que contém vários arquivos.

Hospedagem para sites WordPress da UltraHost

Garantia de reembolso em 30 dias, largura de banda ilimitada e banco de dados, proteção contra DDoS gratuita; desconto de 50% na compra de 3 anos (planos de 4 TB a 10 TB).

página de acesso

Primeiro, crie uma pasta exclusiva para o seu plugin, por exemplo:my-first-pluginNeste diretório, crie o arquivo principal do plugin, que geralmente tem o mesmo nome que o diretório.my-first-plugin.phpO início deste arquivo deve conter uma nota de cabeçalho de plugin que atenda aos padrões do WordPress. Essa nota fornece informações básicas sobre o plugin ao sistema WordPress.

Exemplo de comentário de cabeça no arquivo do plugin principal:

<?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
 */

O “Nome do Plugin” mencionado neste comentário é um campo obrigatório, pois determina o nome exibido do plugin na interface de gerenciamento do backend. Outras informações, como a versão e o autor, ajudam os usuários a entenderem melhor o plugin. Após criar este arquivo, coloque-o no local apropriado./wp-content/plugins/my-first-plugin/Índice. Neste momento, faça login no painel administrativo do seu WordPress e vá para a página “Plugins”. Você deve ver um novo plugin chamado “Meu Primeiro Plugin Personalizado”, e poderá ativá-lo. Embora ele ainda não faça nada, você acabou de criar a estrutura básica de um plugin.

Processo de ativação e desativação de plugins

Os plugins frequentemente precisam executar algumas tarefas de inicialização e limpeza ao serem ativados ou desativados, como criar tabelas no banco de dados, definir opções padrão ou remover dados temporários. O WordPress utiliza dois ganchos (hooks) especiais para gerenciar essas ações:register_activation_hookeregister_deactivation_hook。

Leitura recomendada Do Início ao Domínio: Guia Completo e Melhores Práticas para o Desenvolvimento de Plugins para WordPress。

Você pode definir esses “ganchos” (hooks) no arquivo principal do plugin. Por exemplo, quando o plugin for ativado, podemos querer gravar uma opção de configuração padrão no banco de dados; quando o plugin for desativado, pode ser necessário limpar essa opção. O código de implementação é o seguinte:

// 定义插件激活时执行的函数
function my_plugin_activate() {
    // 添加一个默认选项到数据库
    add_option('my_plugin_default_option', '这是默认值');
    // 或者可以在这里初始化自定义数据库表（需要更复杂的SQL）
}
register_activation_hook(__FILE__, 'my_plugin_activate');

// 定义插件停用时执行的函数
function my_plugin_deactivate() {
    // 删除之前创建的选项
    delete_option('my_plugin_default_option');
    // 注意：通常不在停用钩子中删除数据，以免用户重新激活时丢失设置
    // 更常见的清理工作在卸载钩子中处理
}
register_deactivation_hook(__FILE__, 'my_plugin_deactivate');

É importante notar que…register_deactivation_hookGeralmente, é utilizado para limpezas leves, enquanto a eliminação permanente de dados (como a remoção de tabelas de um banco de dados) deve ser realizada nos “hook” de desinstalação. A funcionalidade de desinstalação precisa ser configurada adequadamente para que isso aconteça.register_uninstall_hookRegistre-se. O uso adequado desses “ganchos” (hooks) garantirá que o comportamento do seu plugin seja padronizado e que nenhum dado redundante seja deixado no site.

Compreender e utilizar ganchos (hooks) e filtros (filters)

O núcleo do desenvolvimento de plugins para o WordPress reside no mecanismo dos “ganchos” (Hooks), que permitem que você insira código personalizado em momentos ou locais específicos para modificar ou expandir as funcionalidades principais do WordPress. Os ganchos são divididos em dois tipos principais: Ações (Actions) e Filtros (Filters).

hospedagem compartilhada da hosting.com

Alto desempenho com CPUs AMD EPYC, armazenamento SSD NVMe e LiteSpeed, suporte interno especializado 24 horas por dia, 7 dias por semana, medidas de segurança avançadas, incluindo SSL, força bruta, malware e proteção contra DDoS, economia de até 73%

página de acesso

Os ganchos de ação (action hooks) permitem que você execute funções personalizadas quando eventos específicos ocorrem. Por exemplo, quando um artigo é publicado…publish_post), ao ser carregado no cabeçalho da página web (wp_head) ou durante a inicialização no painel de administração (admin_initVocê pode usar…add_action()Uma função é usada para “montar” (ou incorporar) o seu código no sistema. Aqui está um exemplo simples: ela adiciona automaticamente um texto personalizado no final de cada artigo.

function add_custom_footer_to_content($content) {
    if (is_single()) { // 仅在单篇文章页面添加
        $custom_text = '<p><em>Obrigado por ler este artigo!</em></p>';
        $content .= $custom_text;
    }
    return $content;
}
// 使用‘the_content’过滤器，注意这是一个过滤器（Filter）的例子
add_filter('the_content', 'add_custom_footer_to_content');

Como mostrado no código acima, na verdade usamos filtros (Filters). Os ganchos dos filtros (filter hooks) são usados para modificar os dados que lhes são passados. A principal diferença entre eles e as ações (actions) é que os filtros devem retornar o valor modificado. Exemplos típicos de filtros incluem…the_content(Alteração do conteúdo do artigo)the_title(Alterar o título) Eexcerpt_length(Modificar o comprimento do resumo). Correspondente a isso.add_filter()A função é usada para montar (ou associar) funções de filtro.

Criar ganchos personalizados para que outros possam expandi-los.

Um plugin bem projetado não apenas utiliza os ganchos (hooks) do núcleo do WordPress, mas também fornece seus próprios ganchos personalizados, para que outros desenvolvedores possam expandir suas funcionalidades.do_action()Uma função pode criar um “gancho de ação” (action hook) para ser utilizado.apply_filters()É possível criar um filtro hook.

Leitura recomendada Guia Completo para Desenvolvimento de Plugins para WordPress: Construa o Seu Próprio Plugin do Zero。

Por exemplo, antes que o seu plugin processe algum dado, forneça um filtro que permita que outras pessoas modifiquem os parâmetros de entrada:

// 定义插件的主要处理函数
function my_plugin_process_data($input_data) {
    // 在核心处理前，允许其他开发者通过过滤器修改 $input_data
    $filtered_data = apply_filters('my_plugin_filter_input', $input_data);

// ... 使用 $filtered_data 进行核心处理 ...

// 在处理完成后，触发一个动作钩子，通知其他开发者
    do_action('my_plugin_after_processing', $filtered_data);

return $result;
}

Ao criar ganchos personalizados, o seu plugin ganha uma boa capacidade de expansão, seguindo a própria filosofia de desenvolvimento do WordPress.

Hospedagem Compartilhada InterServer

Hospedagem compartilhada $2.50 USD por mês, primeiro mês $0.1 USD código promocional tryinterserver, 461 scripts de aplicativos em nuvem, instalação com um clique.

página de acesso

Adicionar uma página de gerenciamento e opções de configuração para o plugin.

A maioria dos plugins práticos necessita de uma interface de gerenciamento em segundo plano, que permita que os administradores do site configurem as opções do plugin. O WordPress oferece uma API abrangente para criar menus de gerenciamento e páginas de configuração.

Primeiramente, você precisa usar…add_action('admin_menu', 'your_function')Use um “gancho” (hook) para registrar um item de menu. Dentro da função correspondente, aplique essa funcionalidade.add_menu_page()ouadd_submenu_page()Funções para adicionar menus principais ou submenus. Aqui está um exemplo básico de como adicionar um menu principal e configurar uma página:

// 钩入 admin_menu 来添加管理菜单
function my_plugin_add_admin_menu() {
    add_menu_page(
        '我的插件设置',           // 页面标题
        '我的插件',               // 菜单标题
        'manage_options',         // 权限（管理员）
        'my-plugin-settings',     // 菜单slug
        'my_plugin_settings_page', // 用于显示页面内容的回调函数
        'dashicons-admin-generic', // 图标（Dashicon）
        80                         // 菜单位置
    );
}
add_action('admin_menu', 'my_plugin_add_admin_menu');

// 定义设置页面的显示内容
function my_plugin_settings_page() {
    // 检查用户权限
    if (!current_user_can('manage_options')) {
        return;
    }
    ?>
    <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
            // 输出设置字段和非ce字段
            settings_fields('my_plugin_options_group');
            do_settings_sections('my-plugin-settings');
            submit_button('保存设置');
            ?>
        <input type="hidden" name="trp-form-language" value="pt"/></form>
    </div>
    &lt;?php
}

Campos de configuração para registro e verificação

Apenas ter uma página não é suficiente; você precisa utilizar a API de Configurações do WordPress (WordPress Settings API) para registrar, armazenar e verificar as opções de configuração de forma segura. Esse processo envolve o uso…register_setting()、add_settings_section()eadd_settings_field()Funções como essas.

O código abaixo mostra como registrar um grupo de opções de configuração e um campo de texto:

// 初始化插件设置
function my_plugin_settings_init() {
    // 注册一个设置选项组及其数据
    register_setting(
        'my_plugin_options_group', // 选项组名，需与settings_fields()参数一致
        'my_plugin_settings',      // 存储在wp_options表中的选项名
        'my_plugin_sanitize_input' // 可选的验证回调函数
    );

// 添加一个设置区域
    add_settings_section(
        'my_plugin_section_main',
        '主要设置',
        null, // 区域描述的回调函数，可为空
        'my-plugin-settings' // 所属页面的slug
    );

// 向该区域添加一个具体的字段
    add_settings_field(
        'my_plugin_field_text',
        '示例文本字段',
        'my_plugin_field_text_render', // 渲染字段HTML的回调函数
        'my-plugin-settings',
        'my_plugin_section_main'
    );
}
add_action('admin_init', 'my_plugin_settings_init');

// 渲染文本输入字段的函数
function my_plugin_field_text_render() {
    $options = get_option('my_plugin_settings');
    $value = $options['text_field'] ?? ''; // PHP 7.0+ 空合并运算符
    ?>
    <input type='text' name='my_plugin_settings[text_field]' value='<?php echo esc_attr($value); ?>'>
    <?php
}

// 清理和验证输入的函数
function my_plugin_sanitize_input($input) {
    $sanitized_input = [];
    if (isset($input['text_field'])) {
        // 清理文本输入，移除非法标签
        $sanitized_input['text_field'] = sanitize_text_field($input['text_field']);
    }
    return $sanitized_input;
}

Através da API Settings, o WordPress lida automaticamente com o salvamento das opções, a verificação de segurança e as verificações de permissões, o que simplifica significativamente o processo de desenvolvimento e aumenta a segurança.

resumos

Através deste guia, percorremos sistematicamente os principais passos do desenvolvimento de plugins para o WordPress: desde a configuração do ambiente e a criação dos arquivos básicos do plugin, até a compreensão e utilização do mecanismo de ganchos (hooks) do WordPress, e, finalmente, a adição de uma interface de gestão profissional e opções de configuração para o plugin. Cada etapa apresenta trechos-chave de código e práticas padrão. O essencial no desenvolvimento de plugins é utilizar ao máximo o vasto sistema de ganchos do WordPress para expandir suas funcionalidades, seguindo ao mesmo tempo as suas especificações de API para garantir segurança e compatibilidade. Lembre-se: começar com uma ideia simples, adicionar funcionalidades gradualmente e realizar testes abrangentes durante todo o processo de desenvolvimento é o caminho mais eficaz para criar plugins de alta qualidade. Em seguida, você pode explorar tópicos mais avançados, como a criação de tipos de artigos personalizados, a adição de códigos encurtados (shortcodes), o tratamento de solicitações AJAX e a internacionalização do seu plugin.

Perguntas frequentes Perguntas frequentes

É necessário dominar o PHP para desenvolver plugins para o WordPress?

Sim, é essencial ter uma base sólida em PHP. Isso porque o núcleo do WordPress e seus plugins são todos escritos em PHP. Você precisa entender a sintaxe do PHP, funções, conceitos de programação orientada a objetos, entre outros. Além disso, um conhecimento básico de HTML, CSS e JavaScript também é muito útil para criar interfaces de usuário e interações.

Quantos arquivos um plugin deve conter?

Não há requisitos obrigatórios. Um plugin pode conter apenas um arquivo principal em PHP. No entanto, à medida que as funcionalidades se tornam mais complexas, é aconselhável modularizar o código em vários arquivos.admin.phpTratamento no backend.public.phpTratamento do lado front-end.includesÉ uma melhor prática armazenar funções comuns em pastas, pois isso ajuda na organização e manutenção do código.

Por que o meu plugin faz com que o site fique com a tela branca após ser ativado?

Isso geralmente é causado por um erro fatal (Fatal Error), como erros de sintaxe, chamadas a funções ou classes que não existem. Por favor, verifique se você já…wp-config.phpFoi ativado.WP_DEBUGModelo, e verifique.wp-content/debug.logInformações de erro no arquivo. Desativar o seu plugin através do FTP ou de um gerenciador de arquivos (renomeando a pasta do plugin) pode restaurar o acesso ao site rapidamente.

Como processar de forma segura os dados enviados pelos usuários no frontend?

Nunca se deve confiar nos dados inseridos pelos usuários. Antes de processar qualquer informação proveniente de formulários, parâmetros de URL ou cookies, é necessário realizar verificações, limpezas e ações de escape (escapamento de caracteres especiais). O WordPress disponibiliza uma grande quantidade de funções de segurança para isso.sanitize_text_field()(Limpar o texto)esc_url()(Escapamento de URL)wp_kses_post()(Filtrar o conteúdo usando os tags HTML permitidos) eintval()(Converte em um número inteiro). Ao exibir os dados em uma página HTML, é essencial usar…esc_html()、esc_attr()Use funções como `escape()` para realizar a escape dos caracteres.

Como posso fazer com que o texto do meu plugin suporte vários idiomas?

Isso precisa ser realizado através da internacionalização (i18n). No seu código, substitua todas as strings que precisam ser traduzidas por suas respectivas versões em outros idiomas.__()ou_e()Encapsulamento da função. Em seguida, configure corretamente as informações de comentário no início do plugin.Text DomaineDomain PathUse uma ferramenta como o Poedit para criar isso..potArquivos de modelo, e geração de versões desses arquivos para diferentes idiomas..poe.moO WordPress carrega automaticamente as traduções correspondentes de acordo com as configurações de idioma do site.