Guia de Introdução ao Desenvolvimento de Plugins para WordPress: construa sua primeira extensão do zero

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

Antes de começar a escrever o código, um ambiente de desenvolvimento adequado é de extrema importância. Isso não só permite que você trabalhe de forma eficiente, mas também simula o ambiente de produção real, evitando problemas de incompatibilidade entre o ambiente local e o ambiente online. Um ambiente de desenvolvimento típico deve incluir um servidor local, um editor de código e ferramentas de depuração.

Primeiramente, você precisa de um ambiente de servidor local capaz de executar o WordPress. Recomendamos o uso de pacotes de ambientes integrados, como Laragon, XAMPP ou Local by Flywheel. Esses ferramentas permitem a instalação automática do Apache/Nginx, PHP e MySQL, poupando você do processo de configuração complicado. Certifique-se de que a versão do PHP esteja compatível com a versão mais recente do WordPress; geralmente, é recomendado usar o PHP 7.4 ou uma versão mais recente. Além disso, no painel de controle do WordPress, na seção “Ferramentas” → “Saúde do Site”, verifique se não existem problemas críticos que possam afetar o desenvolvimento de plugins.

Em segundo lugar, escolha um editor de código poderoso. O Visual Studio Code é uma opção muito popular atualmente; é leve, gratuito e dispõe de uma vasta gama de extensões, como o PHP Intelephense (para sugestões inteligentes de código) e o WordPress Snippet (para fragmentos de código). Outra opção clássica é o PhpStorm, que oferece suporte mais avançado para o desenvolvimento em WordPress, mas é um software pago.

Leitura recomendada Do Zero ao Um: Guia Completo e Práticas de Melhorias para o Desenvolvimento de Plugins para WordPress。

Finalmente, ativar o modo de depuração é um passo essencial no processo de desenvolvimento. Isso é feito alterando os arquivos localizados no diretório raiz do WordPress.wp-config.phpArquivos: Você pode ativar a opção de relatórios de erros detalhados, o que é essencial para identificar e corrigir problemas no código. Encontre a definição no arquivo em questão.WP_DEBUGNo local onde as constantes são definidas, adicione o seguinte código:

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

// 启用 WordPress 调试模式
define( 'WP_DEBUG', true );
// 将错误记录到 /wp-content/debug.log 文件
define( 'WP_DEBUG_LOG', true );
// 在页面上显示错误（开发环境推荐，生产环境必须关闭）
define( 'WP_DEBUG_DISPLAY', true );

Crie o seu primeiro arquivo de plugin.

Um plugin para o WordPress pode ser tão simples que consista em apenas um arquivo. Todos os plugins devem ser armazenados em um determinado local no sistema do WordPress./wp-content/plugins/Cada plugin pode ter seus próprios subdiretórios, o que ajuda a organizar estruturas de código mais complexas.

Comentários na cabeça do plugin

Cada arquivo principal de um plugin deve começar com comentários de cabeçalho em PHP padronizados; é assim que o WordPress reconhece as informações do plugin. Crie um novo arquivo e nomeie-o…my-first-plugin.phpE coloque dentro./wp-content/plugins/my-first-plugin/No diretório. O conteúdo do arquivo é o seguinte:

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

Este comentário fornece todas as informações metadadas do plugin que são exibidas na página de “Plugins” no painel administrativo do WordPress. Entre elas,Text DomaineDomain PathUtilizado para a preparação da internacionalização (i18n) de plugins.

Implementar uma função simples

Agora, vamos adicionar uma função simples a este plugin: adicionar automaticamente uma linha de texto personalizado no final do conteúdo do artigo. Vamos usar as funcionalidades do WordPress para isso.the_contentFilter hook. No que você acabou de criar…my-first-plugin.phpAbaixo das notas de cabeça do arquivo, adicione a seguinte função:

Leitura recomendada Dominar o desenvolvimento de plugins para o WordPress: construindo funcionalidades personalizadas do zero.。

// 在文章内容末尾添加自定义文本
function my_first_plugin_add_footer_text( $content ) {
    // 确保只在主循环的单篇文章页面执行
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $footer_text = '<p><em>Obrigado pela leitura! Este artigo foi apresentado para você por “Meu Primeiro Plugin”.</em></p>';
        $content .= $footer_text;
    }
    return $content;
}
add_filter( 'the_content', 'my_first_plugin_add_footer_text' );

Após salvar o arquivo, faça login no painel administrativo do seu WordPress e vá para a página “Plugins”. Você deve ver um plugin chamado “Meu Primeiro Plugin”. Ative-o, e então navegue por um artigo do blog. Notará que o texto que definimos foi adicionado com sucesso no final do conteúdo do artigo.

Usar a API do núcleo do WordPress

Durante o desenvolvimento avançado, você interagirá frequentemente com as várias APIs fornecidas pelo WordPress. O sistema mais central dessas APIs é o sistema de “ganchos” (Hooks), que inclui “ações” (Actions) e “filtros” (Filters).

Compreender os ganchos de ação (action hooks)

Os ganchos de ação (action hooks) permitem que você execute código personalizado em momentos específicos. Por exemplo, quando um artigo é publicado, você pode querer enviar um e-mail de notificação. Nesse caso, eles são muito úteis.publish_postAções. O exemplo a seguir mostra como criar uma funcionalidade que registra informações no log de erros quando um artigo é publicado:

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

// 定义文章发布时执行的动作函数
function my_first_plugin_log_post_published( $post_id, $post ) {
    // 避免无限循环和非文章类型
    if ( wp_is_post_revision( $post_id ) || $post->post_type != ‘post’ ) {
        return;
    }
    // 记录日志
    error_log( “文章 ID {$post_id} 已发布，标题为：{$post->post_title}” );
}
// 将函数挂载到 publish_post 动作钩子上
add_action( ‘publish_post’， ‘my_first_plugin_log_post_published’， 10, 2 );

funçãoadd_actionO terceiro parâmetro é a prioridade (padrão 10); quanto menor o número, maior a prioridade. O quarto parâmetro é o número de argumentos que a função aceita.

Compreender os ganchos (hooks) dos filtros

Os ganchos (hooks) dos filtros são usados para modificar os dados. No capítulo “Criando seu primeiro arquivo de plugin”, foi isso que utilizamos.the_contentÉ simplesmente um gancho (hook) de filtro. Ele recebe o conteúdo original e permite que você o modifique antes de retorná-lo. Outro exemplo comum é a alteração do comprimento do resumo de um artigo.

// 修改摘要的默认字数
function my_first_plugin_custom_excerpt_length( $length ) {
    return 30; // 将摘要字数改为30字
}
add_filter( ‘excerpt_length’， ‘my_first_plugin_custom_excerpt_length’ );

Adicionar menu de entrada

Para interagir com os usuários, geralmente precisamos adicionar uma página de menu no painel de controle do lado esquerdo do backend do WordPress. Isso pode ser feito através de...add_menu_pageImplementação da função. O código abaixo adiciona uma página de configurações principais para o plugin:

Leitura recomendada Guia Completo para Desenvolvimento de Plugins para WordPress: Construindo Funcionalidades de Extensão de Alta Qualidade do Zero。

// 创建插件管理菜单
function my_first_plugin_add_admin_menu() {
    add_menu_page(
        ‘我的第一个插件设置’， // 页面标题
        ‘我的插件’，           // 菜单标题
        ‘manage_options’，     // 所需权限
        ‘my-first-plugin’，    // 菜单slug
        ‘my_first_plugin_settings_page’， // 回调函数，用于输出页面内容
        ‘dashicons-admin-plugins’， // 图标（可选）
        100                    // 菜单位置（可选）
    );
}
add_action( ‘admin_menu’， ‘my_first_plugin_add_admin_menu’ );

// 设置页面的回调函数
function my_first_plugin_settings_page() {
    ?>
    <div class="“wrap”">
        <h1>As configurações do meu primeiro plugin</h1>
        <p>Esta é a página de configuração dos plugins. No futuro, você poderá adicionar formulários e opções aqui.</p>
    </div>
    &lt;?php
}

Segurança de plugins e melhores práticas

Ao desenvolver plugins para uso por outros, a segurança e a qualidade do código não devem ser negligenciadas. Seguir as melhores práticas pode proteger o site de ataques e garantir a compatibilidade e a manutenibilidade do plugin.

Validação de Dados e Escape

Nunca confie nos dados inseridos pelos usuários ou nos dados provenientes do banco de dados. Antes de exibir esses dados no navegador, é necessário escapá-los; antes de salvá-los no banco de dados, é necessário verificar e limpar esses dados. O WordPress disponibiliza muitas funções de ajuda para isso.

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

• Output de escape: useesc_html()、esc_attr()、esc_url()ewp_kses_post()Funções como essas escapam os dados de acordo com o contexto.
• Verificar a entrada: usarsanitize_text_field()、sanitize_email()、intval()Funções como essas são usadas para limpar os dados dos formulários enviados pelos usuários.

Por exemplo, ao configurar a página para processar os dados do formulário:

$user_input = $_POST[‘some_field’] ?? ‘’; // 使用空合并运算符提供默认值
$clean_input = sanitize_text_field( $user_input ); // 清理数据
update_option( ‘my_plugin_option’， $clean_input ); // 安全存储

Usar métodos que não se baseiam no protocolo CE (Common Edge) nem em verificações de permissões.

Ao processar solicitações de formulários (especialmente as provenientes de admin-ajax.php ou admin-post.php), é necessário utilizar…wp_verify_nonce()Isso é feito para verificar a legitimidade da solicitação e evitar ataques de falsificação de solicitações entre sites (CSRF – Cross-Site Request Forgery). Ao mesmo tempo, é utilizado…current_user_can()Verifique se o usuário atual tem permissão para realizar a operação.

function my_first_plugin_handle_form_submit() {
    // 1. 检查nonce
    if ( ! isset( $_POST[‘my_nonce_field’] ) || ! wp_verify_nonce( $_POST[‘my_nonce_field’]， ‘my_action’ ) ) {
        wp_die( ‘安全校验失败！’ );
    }
    // 2. 检查权限
    if ( ! current_user_can( ‘manage_options’ ) ) {
        wp_die( ‘权限不足！’ );
    }
    // 3. 安全地处理数据…
}

Organização de código e internacionalização

Para plugins complexos, recomenda-se o uso da programação orientada a objetos (POO) para organizar o código, modularizando as funções em classes. Isso melhora a legibilidade e a reutilizabilidade do código.

Ao mesmo tempo, prepare o plugin para internacionalização desde o início. Isso significa que todas as strings direcionadas aos usuários devem utilizar as funções de tradução do WordPress.__()、_e()Realize a embalagem. Revisando as anotações no cabeçalho do plugin, já definimos…Text DomainNo código, deve ser usado da seguinte maneira:

$message = __( ‘感谢阅读！本文由“我的第一个插件”为您呈现。’， ‘my-first-plugin’ );

Em seguida, você pode usar ferramentas como o Poedit para criar o conteúdo desejado..potArquivo de modelo, usado pelos tradutores para gerar textos em diferentes idiomas..moDocumentos.

resumos

Com este guia, você completou o processo essencial para criar um plugin para o WordPress do zero. Apreendeu a configurar um ambiente de desenvolvimento, a criar arquivos de plugins que contêm as devidas anotações de cabeçalho padrão, e a utilizar o poderoso sistema de ganchos (hooks) de ações e filtros do WordPress para adicionar funcionalidades. Também discutimos como adicionar menus de gerenciamento de forma segura, como manipular dados, e enfatizamos a importância da segurança e da internacionalização. O desenvolvimento de plugins é um processo contínuo de aprendizado e prática; o essencial é compreender o sistema de ganchos do WordPress e as diretrizes de segurança. Agora, você pode tentar desenvolver funcionalidades mais complexas, como criar tabelas de banco de dados personalizadas, adicionar códigos encurtados (shortcodes), widgets ou pontos de extremidade de API REST, e construir gradualmente plugins de nível comercial com funcionalidades completas e código robusto.

Perguntas frequentes Perguntas frequentes

Um plugin deve ser colocado em uma pasta separada?

Não, um plugin pode ser apenas um elemento separado (isolado)..phpOs arquivos devem ser colocados diretamente no local desejado./wp-content/plugins/No diretório. No entanto, para qualquer plugin que contenha vários arquivos, recursos (como JS, CSS) ou arquivos que precisem ser traduzidos, é fortemente recomendado usar uma pasta separada para armazenar todos os arquivos relacionados. Isso torna a estrutura do projeto mais clara e facilita a gestão.

Como posso salvar as configurações do meu plugin no banco de dados?

O WordPress oferece uma API de opções muito conveniente. Você pode usá-la.add_option()、get_option()eupdate_option()Existem funções para adicionar, recuperar e atualizar as configurações dos plugins. Esses dados são armazenados de forma segura no WordPress.wp_optionsEm tabelas de bancos de dados, para grandes quantidades de dados estruturados, pode-se considerar serializá-los em arrays ou strings JSON antes de armazená-los.

O plugin que desenvolvi pode causar conflitos com outros plugins?

É possível, especialmente quando os plugins utilizam ganchos (hooks), nomes de funções ou nomes de classes padrão. Para evitar conflitos, as melhores práticas são: adicionar um prefixo único a todas as suas funções, classes e variáveis (por exemplo, usando uma abreviação ou o nome do plugin); utilizar o “slug” do plugin como namespace (isso é possível a partir do PHP 5.3+); e escolher a prioridade correta ao usar os ganchos, para garantir que a ordem de execução seja conforme desejado.

Quais versões do WordPress o plugin precisa ser compatível?

Isso depende do seu público-alvo. Geralmente, é recomendado que o plugin seja compatível com as versões principais atuais, bem como com uma ou duas versões anteriores. Você pode verificar isso nas especificações ou documentação do plugin.readme.txtO arquivo foi processado com sucesso.Requires at least:Os campos são utilizados para especificar a versão mínima exigida do WordPress. Durante o processo de desenvolvimento, deve-se evitar o uso de funções disponíveis apenas em versões mais recentes do WordPress.function_exists()Realizar uma avaliação de compatibilidade a fim de expandir o escopo de aplicação do plugin.