Desenvolvimento aprofundado de plugins para WordPress: criação de seu primeiro plugin personalizado a partir do zero

Noções básicas de plugins para WordPress e ambiente de desenvolvimento

Antes de começar a escrever o código, é essencial entender os conceitos básicos dos plugins do WordPress e configurar um ambiente de desenvolvimento adequado. Um plugin do WordPress é, essencialmente, uma pasta que contém código PHP, e ele expande as funcionalidades do core através da API avançada fornecida pelo WordPress. Os plugins podem variar em complexidade: alguns adicionam apenas um pequeno trecho de código, enquanto outros podem constituir um sistema de gerenciamento completo. O princípio fundamental é “não modificar o código do core”, o que garante que suas funcionalidades personalizadas não sejam perdidas ao atualizar o WordPress.

Para um desenvolvimento eficiente, você precisa de um ambiente de desenvolvimento local. Você pode usar ferramentas como XAMPP, MAMP, Local by Flywheel ou Docker para configurar rapidamente um servidor com PHP e MySQL. Em seguida, instale uma versão mais recente do WordPress. Durante o processo de desenvolvimento, é recomendado que…wp-config.phpO documento está ativado.WP_DEBUG, a fim de expor os erros em tempo hábil.

O “coração” de um plugin é um arquivo PHP principal. As notas de cabeça deste arquivo funcionam como seu “cartão de identidade”; o WordPress utiliza essas informações para reconhecer e gerenciar o plugin em segundo plano. As notas de cabeça de um arquivo principal de plugin padrão são exibidas da seguinte forma:

Leitura recomendada O que são temas do WordPress。

<?php
/**
 * Plugin Name: 我的第一个自定义插件
 * Plugin URI:  https://example.com/my-first-plugin
 * Description: 这是一个用于学习插件开发的简单插件，它将在文章末尾添加自定义内容。
 * Version:     1.0.0
 * Author:      开发者名称
 * License:     GPL v2 or later
 * Text Domain: my-first-plugin
 */

Crie o seu primeiro plugin de funcionalidade.

Vamos começar com uma funcionalidade prática: adicionar automaticamente um texto personalizado no final do conteúdo de cada artigo no site. Este exemplo ilustrará todo o processo central do desenvolvimento de plugins.

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

Arquivo principal do plugin e inicialização

Primeiramente, no WordPress…wp-content/pluginsCrie uma nova pasta na pasta principal, por exemplo:my-first-pluginNesse diretório, crie o arquivo PHP principal; você pode nomeá-lo como “main.php”.my-first-plugin.phpCopie o código dos comentários de cabeça acima para dentro do texto.

Em seguida, precisamos de uma maneira segura de executar o código de inicialização do plugin. A melhor prática é encapsular todas as funções em uma classe ou usar funções em espaços de nomes. Aqui, usaremos uma classe simples para organizar o código. Após as notas de cabeçalho no arquivo principal, adicione a seguinte definição de classe:

if ( ! defined( 'ABSPATH' ) ) {
	exit; // 防止直接访问文件
}

class My_First_Plugin {
    public function __construct() {
        // 构造函数，在这里挂载钩子
    }
}

// 初始化插件
new My_First_Plugin();

if ( ! defined( ‘ABSPATH’ ) )Este código segue os padrões de segurança para o desenvolvimento de plugins para o WordPress, com o objetivo de impedir que os usuários acessem diretamente os arquivos do seu plugin através de um URL.

Usar ganchos para adicionar conteúdo ao rodapé da página do artigo

A arquitetura de plugins do WordPress é baseada no sistema de “ganchos” (Hooks), que são divididos em Ações (Actions) e Filtros (Filters). As Ações permitem que você execute código em momentos específicos, enquanto os Filtros permitem que você modifique dados.

Leitura recomendada Guia definitivo para otimizar o desempenho do site WordPress: uma análise completa desde a configuração básica até os plugins de cache.。

Nosso objetivo é adicionar texto após o conteúdo do artigo; esse é um processo de “filtragem” do conteúdo. Portanto, vamos usar…the_contentEste filtro: modifique o construtor e os métodos na classe da seguinte forma:

class My_First_Plugin {
    public function __construct() {
        // 将自定义方法挂载到‘the_content’过滤器上
        add_filter( 'the_content', array( $this, 'add_footer_to_content' ) );
    }

/**
     * 在文章内容后添加自定义页脚
     *
     * @param string $content 原始文章内容。
     * @return string 修改后的文章内容。
     */
    public function add_footer_to_content( $content ) {
        // 确保只在主循环的单篇文章页面显示
        if ( is_single() && in_the_loop() && is_main_query() ) {
            $custom_footer = '<div class="my-plugin-footer"><p>Obrigado por ler este artigo! Foi gerado por [Meu Primeiro Plugin].</p></div>';
            $content .= $custom_footer;
        }
        return $content;
    }
}

add_filter()A função irá usar o método da classe.add_footer_to_contentRegistre-se emthe_contentFiltros: Quando o WordPress está prestes a exibir o conteúdo de um artigo, ele chama o nosso método e passa o conteúdo original. Utilizamos condições para garantir que o rodapé seja adicionado apenas na página do artigo em si, evitando sua repetição na página inicial ou nas páginas de arquivos. Por fim, adicionamos o HTML personalizado ao conteúdo e retornamos o resultado.

Adicionar opções de gerenciamento para o plugin

Um plugin maduro geralmente permite que os usuários façam configurações no backend. Vamos adicionar uma opção de configuração simples para o texto do rodapé que acabamos de criar, para que os usuários possam personalizar a mensagem exibida.

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 a página do menu de configurações

Nós precisamos adicionar uma subpágina no menu “Configurações” do painel de administração do WordPress. Isso requer o uso de…add_options_page()A função, geralmente, é montada (ou acoplada) em…admin_menuNo gancho de ação.

Primeiramente, adicione um novo método na classe do plugin para registrar menus e páginas:

class My_First_Plugin {
    // ... 之前的构造函数和方法 ...

public function __construct() {
        add_filter( 'the_content', array( $this, 'add_footer_to_content' ) );
        // 挂载后台管理菜单
        add_action( 'admin_menu', array( $this, 'add_admin_menu' ) );
        // 挂载初始化设置选项
        add_action( 'admin_init', array( $this, 'settings_init' ) );
    }

public function add_admin_menu() {
        add_options_page(
            '我的第一个插件设置', // 页面标题
            '自定义页脚设置',     // 菜单标题
            'manage_options',     // 所需权限
            'my-first-plugin',    // 菜单slug
            array( $this, 'options_page_html' ) // 回调函数，用于输出页面HTML
        );
    }
}

Campos de configuração de registro e página de renderização

Em seguida, precisaremos usar a API de Configurações do WordPress (WordPress Settings API) para registrar, salvar e verificar opções de forma segura. Isso envolve…register_setting(), add_settings_section()eadd_settings_field()Funções como essas.

Leitura recomendada O que é o WooCommerce? Uma explicação detalhada sobre suas funcionalidades principais e cenários de aplicação。

A função pública settings_init() {
    // Registrar um grupo de opções de configuração
    register_setting( 'my_first_plugin_settings', 'my_first_plugin_options' );

// Adicionar uma seção de configuração na página
    add_settings_section(
        'my_first_plugin_section',
        'Configuração do conteúdo do rodapé',
        array( $this, 'section_callback' ),
        'my-first-plugin'
    );

// Adicionar um campo a essa seção
    add_settings_field(
        'footer_text',
        'Texto para exibir no rodapé',
        array( $this, 'footer_text_field_render' ),
        'my-first-plugin',
        'my_first_plugin_section'
    );
}

public function section_callback() {
    echo '  A função pública settings_init() {
    // Registrar um grupo de opções de configuração
    register_setting( 'my_first_plugin_settings', 'my_first_plugin_options' );

// Adicionar uma seção de configuração na página
    add_settings_section(
        'my_first_plugin_section',
        'Configuração do conteúdo do rodapé',
        array( $this, 'section_callback' ),
        'my-first-plugin'
    );

// Adicionar um campo a essa seção
    add_settings_field(
        'footer_text',
        'Texto para exibir no rodapé',
        array( $this, 'footer_text_field_render' ),
        'my-first-plugin',
        'my_first_plugin_section'
    );
}

public function section_callback() {
    echo '<p>Configure aqui o texto que será exibido no final do artigo.</p>'
    <input type='text' name='my_first_plugin_options[footer_text]' value='<?php echo esc_attr( $value ); ?>' style='width: 400px;'>
    <p class="description">Suporta etiquetas HTML simples, como… <strong>, <em>, <a>。</p>
    
    <div class="wrap">
        <h1></h1>
        <form action='/pt/options.php/' method='post' data-trp-original-action="options.php">
            
        <input type="hidden" name="trp-form-language" value="pt"/></form>
    </div>
    &lt;?php
}

Por fim, modifique a função de exibição no front-end.add_footer_to_contentPara que ele leia o texto das opções do banco de dados:

funcção pública add_footer_to_content( $content ) {
    se ( é_single() e in_the_loop() e é_main_query() ) {
        $options = get_option( 'my_first_plugin_options' );
        $footer_text = $options['footer_text'] ?? 'Obrigado por ler este artigo! Gerado por [Meu Primeiro Plugin]';
        $custom_footer = ' <';
    }
  }&#039;<div class="my-plugin-footer"><p>'`. wp_kses_post($footer_text)`.'</p></div>';
        $content .= $custom_footer;
    }
    return $content;
}

wp_kses_post()A função garante que apenas etiquetas HTML seguras sejam permitidas no texto inserido pelo usuário, o que representa uma importante medida de segurança.

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

Internacionalização de plugins e melhores práticas

Para que o plugin possa ser usado por usuários em todo o mundo, a internacionalização (i18n) é um passo essencial. O WordPress utiliza o framework GNU gettext para realizar as traduções.

Campo de texto e função de tradução

Primeiro, certifique-se de que a definição esteja presente nas notas de cabeça do seu plugin.Text DomainPor exemplomy-first-pluginEm seguida, em todos os locais das strings que precisam ser traduzidas no plugin, use uma função específica para envolvê-las.

Modifiquei o nosso código anterior para adicionar suporte à tradução do texto a ser exibido.

// 在构造函数中加载翻译文件
public function __construct() {
    // ... 其他钩子 ...
    add_action( 'plugins_loaded', array( $this, 'load_textdomain' ) );
}

public function load_textdomain() {
    load_plugin_textdomain(
        'my-first-plugin',
        false,
        dirname( plugin_basename( __FILE__ ) ) . '/languages/'
    );
}

// 修改设置页面的字符串
public function section_callback() {
    echo '<p>'\n' . esc_html__( 'Aqui, configure o conteúdo do texto que será exibido no final do artigo.', 'my-first-plugin' ) . '</p>'
    <input type='text' name='my_first_plugin_options[footer_text]' value='<?php echo esc_attr( $value ); ?>' style='width: 400px;'>
    <p class="description">&lt;?php esc_html_e( &#039;支持简单的HTML标签，如 <strong>, <em>, <a>。', 'my-first-plugin' ); ?&gt;</p>
    &lt;?php
}

// Nota: o “texto do rodapé” introduzido pelo utilizador na interface front-end não necessita, normalmente, de ser traduzido, uma vez que se trata de um conteúdo específico definido pelo administrador.

__()Usado para traduzir e retornar strings.esc_html__()Usado para traduzir e escapar o conteúdo HTML gerado._e()Usado para traduzir e exibir diretamente uma string. O segundo parâmetro da função é o campo de texto, que deve ser consistente com o definido pelo plugin.

Segurança, desempenho e organização do código

Além da internacionalização, também é necessário seguir as seguintes melhores práticas:
1. Segurança: Verifique, limpe e escape todos os dados inseridos pelos usuários. Utilize métodos de validação adequados para garantir a segurança do sistema.sanitize_text_field(), esc_html(), wp_kses_post()E funções. Usarwp_nonce_field()Prevenir ataques CSRF (Cross-Site Request Forgery).
2. Desempenho: Use os “ganchos” (hooks) de forma racional para evitar a execução de consultas desnecessárias ao banco de dados a cada carregamento da página. Pode-se considerar o uso de um cache temporário (transient cache) para os resultados gerados.
3. Organização do código: Para plugins complexos, os arquivos devem ser divididos em módulos funcionais. O arquivo principal é responsável pela inicialização, enquanto as classes e métodos devem ser colocados em arquivos específicos.includes/O diretório onde os recursos front-end (CSS, JS) são armazenados…assets/Catálogo.
4. Desinstalação e limpeza: Se o seu plugin criou tabelas de banco de dados ou opções, deve ser fornecida uma função de desinstalação para limpar esses dados. Isso pode ser feito através de um processo independente…uninstall.phpO arquivo é usado para implementar isso.

resumos

Através deste tutorial, completamos todo o processo de desenvolvimento de um plugin personalizado para o WordPress com funcionalidades básicas: desde a configuração do ambiente, a criação do esqueleto do plugin, à adição de funcionalidades utilizando o sistema de ganchos (hooks), até a implementação da página de configurações do backend, além de abordarmos práticas de internacionalização e segurança. Você aprendeu como usar esses recursos para desenvolver plugins eficazes para o WordPress.add_filtereadd_actionInteragir com o núcleo do WordPress: como usar a API Settings para criar páginas de opções confiáveis, e como fazer isso?load_plugin_textdomainFaça com que o plugin suporte múltiplas línguas. Lembre-se de que, ao desenvolver plugins, a segurança, a manutenibilidade e a experiência do usuário são os fatores mais importantes a serem considerados. Com base nisso, você pode continuar explorando funcionalidades mais avançadas, como tipos de artigos personalizados, metadados, códigos curtos e endpoints de API REST, para criar extensões para o WordPress ainda mais poderosas.

Perguntas frequentes Perguntas frequentes

Por que o meu plugin não está aparecendo no menu de administração?

Isso geralmente é causado por problemas de permissões ou erros no código. Primeiro, por favor, confira se…add_options_pageouadd_menu_pageOs parâmetros de permissão especificados na função (como…)‘manage_options’Deve corresponder ao papel do usuário com o qual você está atualmente conectado. Em seguida, verifique…admin_menuO hook foi montado corretamente, e a função de retorno não contém erros de sintaxe que possam interromper a execução do PHP. O método mais simples é ativar essa funcionalidade no painel de administração do WordPress.WP_DEBUGVerifique se há informações de erro relacionadas sendo exibidas.

Como adicionar arquivos CSS e JavaScript personalizados para um plugin?

A maneira correta de fazer é usar…wp_enqueue_style()ewp_enqueue_script()Funções. No que diz respeito aos recursos front-end, eles devem ser montados (ou carregados) no ambiente de execução apropriado.wp_enqueue_scriptsNo gancho de ação; para os recursos do backend de gestão, eles são montados (ou conectados) nesse gancho.admin_enqueue_scriptsNo gancho.

Na sua classe de plugin, você pode adicionar o seguinte método:

public function enqueue_frontend_assets() {
    wp_enqueue_style( ‘my-plugin-style’, plugin_dir_url( __FILE__ ) . ‘assets/css/style.css’, array(), ‘1.0.0’ );
}

Em seguida, no construtor, através de…add_action( ‘wp_enqueue_scripts’, array( $this, ‘enqueue_frontend_assets’ ) );Registre-se. Isso garantirá que o gerenciamento de dependências seja feito corretamente e que não haja conflitos com outros plugins ou temas.

Como posso limpar as opções de dados que criei quando os usuários desinstalam o plugin?

O WordPress oferece duas principais maneiras de realizar essa tarefa. A primeira é registrar um “hook” de desinstalação, mas esse método não é muito utilizado em plugins orientados a objetos. A maneira mais recomendada e padrão é criar um novo plugin específico para essa finalidade.uninstall.phpO arquivo está no mesmo nível que o seu arquivo de plugin principal.

Quando um usuário exclui um plugin pelo painel administrativo do WordPress, o WordPress verifica automaticamente e executa esse arquivo.uninstall.phpNeste caso, você precisa verificar primeiro…WP_UNINSTALL_PLUGINAs constantes são definidas e, em seguida, todos os dados criados pelo plugin, como opções personalizadas e tabelas de banco de dados, são removidos de forma segura. Por exemplo:

if ( ! defined( ‘WP_UNINSTALL_PLUGIN’ ) ) {
    exit;
}
delete_option( ‘my_first_plugin_options’ );
// 如果有自定义表：$wpdb->query( “DROP TABLE IF EXISTS {$wpdb->prefix}my_table” );

Como meu plugin pode ser compatível com mais versões do WordPress?

O segredo para manter a compatibilidade é usar com cautela as funções e características das novas versões, e fornecer alternativas para as versões antigas. Antes de chamar uma função que pode só estar disponível na nova versão, é necessário…function_exists()Faça uma verificação. Por exemplo, se você quiser usar recursos introduzidos na versão 5.0…wp_dateAs funções podem:

if ( function_exists( ‘wp_date’ ) ) {
    $date = wp_date( get_option( ‘date_format’ ), $timestamp );
} else {
    $date = date_i18n( get_option( ‘date_format’ ), $timestamp );
}

Ao mesmo tempo, declare claramente na parte de comentários do cabeçalho do plugin e no arquivo de instruções (readme) a versão mínima do WordPress para a qual o plugin foi testado. Realizar testes periodicamente em versões mais antigas do WordPress é a melhor maneira de garantir a compatibilidade.