Guia Completo para Desenvolvimento de Plugins para WordPress: Construa o Seu Primeiro Plugin Funcional do Zero

Antes de começar, certifique-se de que você possui um ambiente local ou online do WordPress para desenvolvimento e teste. Ambientes integrados como Local, XAMPP ou MAMP são boas opções. Além disso, você precisará de um computador com um editor de código (como Visual Studio Code ou PhpStorm) instalado, bem como conhecimentos básicos de PHP, HTML, CSS e JavaScript.

Ter um ambiente de desenvolvimento claro é a base para todo o trabalho subsequente, pois permite que você se concentre na lógica do código, e não na configuração do ambiente.

Crie o seu primeiro arquivo de plugin.

Um plugin para WordPress precisa de pelo menos um arquivo PHP principal, e esse arquivo deve conter um comentário de cabeçalho específico, usado para fornecer informações metadados ao sistema WordPress.

Leitura recomendada Guia Completo para Desenvolvimento de Plugins para WordPress: Construindo Plugins Profissionais do Zero。

Comments no cabeçalho do plugin e no arquivo principal

Primeiramente, no diretório de instalação do WordPress… wp-content/plugins/ Dentro da pasta, crie uma nova pasta, por exemplo… my-first-pluginNesse diretório, crie o arquivo principal. my-first-plugin.phpNo início do arquivo, deve-se adicionar a nota de cabeçalho padrão do plugin.

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

<?php
/**
 * Plugin Name:       我的第一个功能插件
 * Plugin URI:        https://yourwebsite.com/my-first-plugin
 * Description:       这是一个学习 WordPress 插件开发的示例插件，用于在前端页面底部添加自定义文本。
 * Version:           1.0.0
 * Author:            你的名字
 * Author URI:        https://yourwebsite.com
 * License:           GPL v2 or later
 * Text Domain:       my-first-plugin
 */

Este comentário é como o “cartão de identidade” do plugin. O WordPress o lê para entender como o plugin funciona e como interagir com ele. Plugin Name O nome do plugin será exibido na interface de gerenciamento do backend, e outras informações, como a versão e a descrição, também serão mostradas nos respectivos locais. Após salvar o arquivo, você poderá ver esse plugin desativado na página de “Plugins” do backend do WordPress.

Implementação da funcionalidade: Adição de ganchos de ação (action hooks).

A lógica dos plugins é principalmente integrada através do sistema de ganchos (Hooks) do WordPress. Nós vamos usar isso. wp_footer Este “gancho de ação” (action hook) exibe um texto no rodapé da página do site.

Abaixo das notas no cabeçalho do plugin, adicione o seguinte código:

// 在网站页脚添加自定义文本
function mfp_add_footer_text() {
    echo '<p style="text-align: center; color: #666;">Obrigado pela leitura! Este rodapé foi gerado pelo “Meu Primeiro Plugin de Funcionalidade”.</p>';
}
add_action( 'wp_footer', 'mfp_add_footer_text' );

Aqui, criamos algo chamado… mfp_add_footer_text A função personalizada. Em seguida, use-a. add_action() A função “monta” essa outra função em… wp_footer Neste gancho… Quando o WordPress chegar à posição do rodapé, nossa função será automaticamente chamada, e o trecho de HTML correspondente será exibido.

Leitura recomendada Construa passo a passo o seu primeiro plugin para o WordPress: desde o básico até o desenvolvimento prático.。

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

Um plugin com funcionalidades completas geralmente requer uma interface de configuração no backend, que permita aos usuários ajustar o comportamento do plugin sem a necessidade de modificar o código. Vamos criar uma página de opções simples.

Criar item de menu de gerenciamento

Primeiro, precisamos usar add_action( ‘admin_menu’, … ) Vamos adicionar um novo item de menu no painel de administração. Continue adicionando o seguinte código no seu arquivo principal do plugin:

// 添加管理菜单
function mfp_add_admin_menu() {
    add_menu_page(
        '我的插件设置',          // 页面标题
        '我的插件',             // 菜单标题
        'manage_options',       // 权限要求
        'mfp-settings',         // 菜单slug
        'mfp_settings_page',    // 显示页面内容的回调函数
        'dashicons-admin-generic', // 图标（使用Dashicons）
        30                      // 菜单位置
    );
}
add_action( 'admin_menu', 'mfp_add_admin_menu' );

add_menu_page() As funções são APIs fornecidas pelo núcleo do WordPress, utilizadas para adicionar menus principais na barra de navegação esquerda. Nós especificamos as permissões necessárias para o acesso a essas funções. manage_optionsGeralmente, apenas o administrador tem acesso a essas informações.

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

Criar uma página de configurações e um formulário

Em seguida, precisamos definir as funções de callback mencionadas acima. mfp_settings_page Renderizar o conteúdo HTML da página de configurações e processar o salvamento dos dados do formulário.

// 设置页面的HTML内容
function mfp_settings_page() {
    // 检查用户权限
    if ( !current_user_can( ‘manage_options’ ) ) {
        return;
    }

// 处理表单提交
    if ( isset( $_POST[‘mfp_footer_text’] ) ) {
        // 验证和清理输入数据
        $new_text = sanitize_text_field( $_POST[‘mfp_footer_text’] );
        // 使用 update_option 将数据保存到数据库
        update_option( ‘mfp_footer_text’, $new_text );
        echo ‘<div class="“notice" notice-success is-dismissible”><p>A configuração foi salva!</p></div>’;
    }

// 从数据库获取现有值，用于填充表单
    $current_text = get_option( ‘mfp_footer_text’, ‘这是默认的页脚文本。’ );
    ?&gt;
    <div class="“wrap”">
        <h1>Configurações do meu plugin</h1>
        <form method="“post”" action="/pt/“”/" data-trp-original-action="“”">
            <?php wp_nonce_field( ‘mfp_save_settings’, ‘mfp_settings_nonce’ ); ?>
            <table class="“form-table”">
                <tr>
                    <th scope="“row”"><label for="“mfp_footer_text”">Texto personalizado para o rodapé da página</label></th>
                    <td>
                        <input name="“mfp_footer_text”" type="“text”" id="“mfp_footer_text”" value="“NO NUMERIC NOISE KEY" 1001” class="“regular-text”">
                        <p class="“description”">Este texto será exibido no fundo de todas as páginas do site.</p>
                    </td>
                </tr>
            </table>
            <?php submit_button(); ?>
        <input type="hidden" name="trp-form-language" value="pt"/></form>
    </div>
    &lt;?php
}

Esta função desempenha várias tarefas essenciais: verificação de permissões e processamento do envio de formulários (utilizando…) update_option Armazenamento, bem como a renderização da interface de formulários. Note que foi utilizado… sanitize_text_field() e esc_attr() Funções de segurança são utilizadas para prevenir ataques XSS (Cross-Site Scripting).

Tornar a funcionalidade configurável

Agora, precisamos modificar a função que gera o texto do rodapé da página anterior, para que ela leia as configurações do usuário do banco de dados, em vez de exibir texto hardcoded.

Leitura recomendada Dominando o Desenvolvimento de Plugins para WordPress do Zero: Um Guia Completo com Exercícios Práticos。

// 更新页脚文本函数，使其可配置
function mfp_add_footer_text() {
    // 从数据库获取保存的文本，如果没有则使用默认值
    $footer_text = get_option( ‘mfp_footer_text’, ‘感谢阅读！本页脚由“我的第一个功能插件”生成。’ );
    if ( !empty( $footer_text ) ) {
        echo ‘<p style="“text-align:" center; color: #666;”>’ . esc_html( $footer_text ) . ‘</p>’;
    }
}
add_action( ‘wp_footer’, ‘mfp_add_footer_text’ );

Dessa forma, um plugin com funcionalidades básicas de gerenciamento do backend está pronto. Os usuários podem modificar textos no backend, e essas alterações serão refletidas em tempo real no site front-end.

Melhores Práticas de Desenvolvimento de Plugins e Segurança

Seguir as melhores práticas não só melhora a qualidade do código, como também garante a segurança e a compatibilidade dos plugins.

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

Usar prefixos e namespaces

Todos os funções, classes, variáveis e nomes de opções que você definiu devem usar um prefixo único para evitar conflitos com o core do WordPress, temas ou outros plugins. Neste exemplo, usamos… mfp_ “Meu Primeiro Plugin” pode ser usado como um prefixo para identificar os primeiros plugins que você desenvolve. Para plugins mais complexos, você pode considerar o uso de namespaces PHP.

Validação de dados, limpeza e escape

Este é o ponto central da segurança dos plugins: todos os dados inseridos pelos usuários (incluindo os administradores) devem ser considerados não confiáveis.
* 验证 (Validation): 检查数据是否符合预期格式（如是否为邮箱、数字）。
* 清理 (Sanitization): 在将数据存入数据库或用于其他操作前，移除其中的非法或危险字符。我们使用了 sanitize_text_field()。
* 转义 (Escaping): 在将数据从数据库输出到 HTML、JavaScript 或 URL 时，进行转义以防止 XSS 攻击。我们使用了 esc_html() e esc_attr()。

Preparação para a internacionalização

Para que o plugin possa ser traduzido por usuários de todo o mundo, todas as strings direcionadas aos usuários devem ser encapsuladas nas funções de internacionalização do WordPress. Modifique a forma como nossas strings são exibidas:

echo ‘<p style="“text-align:" center; color: #666;”>’ . esc_html__( ‘感谢阅读！本页脚由“我的第一个功能插件”生成。’, ‘my-first-plugin’ ) . ‘</p>’;

E assegure-se de que as informações corretas tenham sido definidas nas notas de cabeça do plugin. Text DomainEm seguida, use ferramentas como o Poedit para criar o arquivo de modelo (.pot).

Depuração, teste e preparação para lançamento

Antes de colocar um plugin em um ambiente de produção ou enviá-lo para o diretório oficial, é essencial realizar testes adequados.

Ativar o modo de depuração

No arquivo de configuração do WordPress wp-config.php Ao ativar o modo de depuração, você consegue ver erros, avisos e notificações do PHP, o que é de grande ajuda no desenvolvimento.

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

Realizar testes de funcionalidade e compatibilidade.

• Teste de Funcionalidade: Testar todas as funcionalidades do plugin uma por uma: ativar/desativar, salvar configurações e verificar se a saída na interface frontal está correta.
• Testes de compatibilidade: Teste o seu plugin em diferentes versões do WordPress (especialmente as mais antigas), versões do PHP (7.4+ e 8.x), bem como em temas populares e outros plugins comumente utilizados.
• Verificação de segurança: É possível utilizar ferramentas automatizadas ou revisar o código manualmente para garantir que não existam vulnerabilidades como injeções SQL, XSS ou CSRF. O campo Nonce que adicionamos anteriormente foi exatamente para prevenir ataques de tipo CSRF.

Preparando para publicar o arquivo.

Se o plano for de publicar o conteúdo, é necessária uma estrutura de arquivo padrão. Geralmente, essa estrutura inclui:
* 主插件文件 (如 my-first-plugin.php)
* readme.txtDeve ser escrito de acordo com o formato especificado pelo WordPress.org, para ser exibido na página do diretório de plugins.
* assets Pastas: Usadas para armazenar ícones, capturas de tela, entre outros arquivos.
* languages Pastas: Locais onde os arquivos de tradução (.po/.mo) são armazenados.
* includes Pastas: Para armazenar outros arquivos de classe PHP.
* uninstall.phpDefinir as ações de limpeza que serão executadas quando um plugin for removido (por exemplo, a opção de excluir dados do banco de dados).

resumos

Com este guia, você completou todo o processo de desenvolvimento de um plugin funcional básico para o WordPress: desde a criação do arquivo principal que contém as informações de cabeçalho padrão, até a adição de funcionalidades utilizando ganchos de ação (action hooks), passando pela construção de uma página de configurações completa no painel administrativo e pela garantia de sua segurança. Destacamos as melhores práticas, como o uso de prefixos, o tratamento seguro dos dados e a internacionalização, e também fornecemos uma breve introdução aos preparativos necessários para a depuração (debugging) e o lançamento do plugin.

Lembre-se: a essência do desenvolvimento de plugins reside no entendimento e no uso inteligente do vasto sistema de ganchos (Hooks) e filtros (Filters) do WordPress. Partindo desse pequeno plugin, você pode continuar explorando como adicionar códigos encurtados (Shortcodes), widgets, tipos de artigos personalizados (Custom Post Types – CPTs) ou pontos de extremidade de API REST, a fim de criar plugins de nível comercial que sejam poderosos, flexíveis e compatíveis com os padrões.

Perguntas frequentes Perguntas frequentes

Em que diretório os plugins devem ser colocados?

Os plugins do WordPress devem ser colocados em wp-content/plugins/ Os plugins estão localizados dentro de um diretório específico. Cada plugin pode ser um arquivo PHP independente (especialmente no caso de plugins muito simples), mas a prática mais comum é criar uma pasta com o nome do plugin e armazenar o arquivo principal e outros arquivos de recursos nela.

Como excluir os dados criados por um plugin?

Quando um usuário clica no botão “Excluir” no painel de controle do plugin no backend, por padrão, apenas o arquivo do plugin é removido. No entanto, as opções do plugin armazenadas no banco de dados (como tabelas de configurações) permanecem intactas.wp_optionsOs dados contidos nesse arquivo serão mantidos. Para uma limpeza completa, você precisará criar um novo arquivo ou procedimento que elimine todos os dados existentes. uninstall.php Arquivo, e use-o dentro dele. delete_option() Uma função é utilizada para remover as opções relacionadas. Este arquivo é chamado apenas quando o usuário remove o plugin através da funcionalidade de exclusão do WordPress.

Qual é a diferença entre as ações e os filtros em um Hook (Gancho)?

Action Hooks (uso) add_action()Isso permite que você insira e execute um trecho de código em um determinado momento no WordPress, sem que seja esperado um retorno de valor. Por exemplo, você pode executar uma função no cabeçalho da página, no rodapé ou ao publicar um artigo.

Ferramentas de filtro (Filter Hooks) em uso add_filter()Isso permite que você modifique os dados transmitidos no processo. Ele recebe um valor e, após o processamento, deve retornar outro valor. Por exemplo, modificar o título de um artigo, o conteúdo de um comentário ou os resultados de uma consulta.

Por que o meu plugin não é exibido em segundo plano?

Primeiramente, verifique se o arquivo PHP principal do seu plugin está localizado no diretório correto e se as notas de cabeçalho do plugin (especialmente…) estão presentes e corretas. Plugin Name:Primeiro, verifique se o formato do arquivo está correto e sem erros. Em seguida, cheque se o arquivo contém erros gramaticais. Você pode fazer isso… wp-config.php Ativar em... WP_DEBUG Veja as possíveis mensagens de erro.