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

Ambiente de desenvolvimento de plugins para WordPress e preparações básicas

Antes de começar a escrever o código, um ambiente de desenvolvimento estável e eficiente é de extrema importância. Isso não só melhora a sua eficiência de desenvolvimento, mas também o ajuda a seguir as melhores práticas, garantindo a qualidade e a compatibilidade dos plugins.

Primeiramente, você precisa de um ambiente de desenvolvimento local para WordPress. Você pode usar ferramentas como XAMPP, MAMP, Local by Flywheel ou Docker para configurar rapidamente o ambiente. Certifique-se de que o seu ambiente esteja utilizando uma versão mais recente do PHP (recomendamos a versão 7.4 ou superior) e do MySQL/MariaDB. Um ambiente de desenvolvimento local permite que você faça testes e depurações de forma livre, sem afetar o site online.

Em segundo lugar, você precisa de um editor de código ou de um ambiente de desenvolvimento integrado (IDE). O Visual Studio Code, o PhpStorm ou o Sublime Text são ótimas opções, pois oferecem funcionalidades como realce de sintaxe, sugestões de código e depuração. Além disso, é recomendável instalar ferramentas de qualidade de código, como o PHP_CodeSniffer, e configurar os padrões de codificação do WordPress, para garantir que o estilo do seu código esteja em conformidade com o core do WordPress.

Leitura recomendada Guia Completo para Desenvolvimento de Plugins para WordPress: Desde o Início até a Construção de Extensões de Nível Profissional。

Finalmente, entender a estrutura básica dos plugins do WordPress é o primeiro passo. Um plugin muito simples necessita apenas de um arquivo PHP principal, no qual as informações específicas do plugin devem ser incluídas no início do arquivo, na forma de comentários. Esse arquivo é a “porta de entrada” para o plugin, e o WordPress utiliza essas informações para identificá-lo e gerenciá-lo.

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

Crie o seu primeiro arquivo de plugin.

Vamos começar criando o plugin mais simples possível, o “Hello World”. Esse processo ajudará você a entender a estrutura básica de um plugin e como o WordPress reconhece esses plugins.

Primeiramente, dentro do diretório de instalação do seu WordPress…wp-content/pluginsDentro da pasta, crie uma nova pasta. O nome da pasta deve ser único, descritivo e ser composto apenas por letras minúsculas e hifens (–), por exemplo:my-first-plugin。

Dentro dessa pasta, crie um arquivo PHP principal. O nome do arquivo geralmente é o mesmo que o nome da pasta, por exemplo:my-first-plugin.phpNo topo deste arquivo, você deve adicionar uma nota de cabeça para o plugin que esteja de acordo com os padrões do WordPress. Esta nota é como o “cartão de identidade” do plugin, contendo informações como o nome, a descrição, a versão, o autor, etc. Sem essa nota, o WordPress não conseguirá encontrar o seu plugin na lista de plugins do backend.

A seguir, está um exemplo de um arquivo de plugin muito básico:

Leitura recomendada Começando do zero: Por que escolher o desenvolvimento de plugins para o WordPress?。

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

// 防止直接访问文件
if ( ! defined( 'ABSPATH' ) ) {
    exit; // 如果ABSPATH未定义，则退出
}

Depois de salvar esse arquivo, faça login no painel administrativo do seu WordPress e vá para a página “Plugins”. Você deve ver “Meu Primeiro Plugin” na lista de plugins. Nesse momento, você pode ativá-lo, mas ele ainda não fará nada. O código contido no arquivo…if ( ! defined( ‘ABSPATH’ ) )A verificação é uma prática de segurança importante, utilizada para impedir que os usuários acessem diretamente os arquivos do seu plugin através de um URL, garantindo que o código seja executado apenas no ambiente do WordPress.

Adicionar funcionalidades essenciais ao plugin

Um plugin ativado precisa executar algumas ações. No WordPress, isso é realizado principalmente através dos “Action Hooks” (Gancho de Ação) e dos “Filter Hooks” (Gancho de Filtro). Eles são a pedra fundamental da arquitetura dos plugins do WordPress, permitindo que você insira seu próprio código em momentos específicos ou modifique dados.

Utilize os ganchos de ação para adicionar notificações no painel de administração.

Os ganchos de ação (action hooks) permitem que você execute suas próprias funções em momentos específicos durante a execução do WordPress (por exemplo, após a inicialização, ao carregar o cabeçalho da página ou ao salvar um artigo). Vamos adicionar uma funcionalidade simples: exibir uma mensagem de boas-vindas no topo do painel de administração do WordPress.

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

Nós vamos usar.admin_noticesEste “action hook”. Primeiramente, você precisa criar uma função para gerar o conteúdo em HTML e, em seguida, utilizá-la.add_action()A função “monta” essa outra função no hook (ponto de conexão específico).

No seu arquivo principal do plugin, adicione o seguinte código:

/**
 * 在管理后台显示欢迎通知
 */
function myfp_display_admin_notice() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p>Bem-vindo ao uso do “Meu Primeiro Plugin”! O plugin foi ativado com sucesso.</p>
    </div>
    &lt;?php
}
// 将函数挂载到 admin_notices 动作钩子
add_action( &#039;admin_notices&#039;, &#039;myfp_display_admin_notice&#039; );

Salve e atualize o painel administrativo do seu WordPress; você deve ver uma caixa de alerta verde de sucesso no topo da página. Observe que o nome da função…myfp_display_admin_noticeFoi utilizado um prefixo.myfp_(Derivado da abreviação do nome do plugin) Isso é para evitar conflitos com os nomes de funções de outros plugins ou temas; trata-se de uma convenção de nomeação que deve ser seguida.

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

Usar os ganchos dos filtros para modificar o conteúdo dos artigos

Os “ganchos de filtro” (filter hooks) permitem que você modifique os dados transmitidos no WordPress. Por exemplo, você pode alterar o conteúdo, o título ou o resumo de um artigo antes que eles sejam exibidos. Vamos criar uma funcionalidade que adicione automaticamente uma declaração de direitos autorais no final de cada artigo.

Nós vamos usar.the_contentEste filtro de gancho… Você precisa criar um componente que receba o conteúdo original.$contentModifique a função correspondente e, em seguida, retorne o conteúdo modificado.

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

Adicione o seguinte código ao seu arquivo de plugin:

/**
 * 在文章内容末尾添加版权声明
 * @param string $content 原始的文章内容
 * @return string 修改后的文章内容
 */
function myfp_add_copyright_to_content( $content ) {
    // 仅对主循环中的单篇文章页面生效
    if ( is_single() && in_the_loop() && is_main_query() ) {
        $copyright_text = '<p><em>Os direitos de autor deste artigo pertencem a este site. Por favor, indique a fonte ao republicá-lo.</em></p>';
        $content .= $copyright_text;
    }
    return $content;
}
// 将函数挂载到 the_content 过滤器钩子，优先级为10
add_filter( 'the_content', 'myfp_add_copyright_to_content', 10 );

Agora, sempre que você visualiza qualquer artigo no site, uma declaração de direitos autorais que você adicionou será exibida no final do conteúdo. As condições de avaliação estão contidas na função.is_single() && in_the_loop() && is_main_query()Muito importante: isso garante que este texto seja exibido apenas no ciclo principal da página do artigo em si, e não na lista da página inicial, em ferramentas adicionais ou em outros locais. É um detalhe crucial a ser considerado ao desenvolver plugins de alta qualidade.

Internacionalização de plugins e melhores práticas

Para que o seu plugin possa ser usado por usuários de todo o mundo, a internacionalização (i18n) é um passo essencial. O WordPress disponibiliza funções completas para suportar a tradução de textos contidos no plugin para outros idiomas.

Preparar o texto do plugin para suportar a tradução.

Você precisa usar uma função específica para encapsular todas as strings que são exibidas aos usuários no plugin. A mais comum é…()Usado para obter a tradução._e()Usado para exibir diretamente a tradução, bem como…esc_html()Usado em contextos que exigem a escape de caracteres HTML.

Primeiro, modifiquemos o texto nas funções de notificação e de direitos autorais que criamos anteriormente, utilizando a função de tradução:

function myfp_display_admin_notice() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p><?php _e( '欢迎使用“我的第一个插件”！插件已成功激活。', 'my-first-plugin' ); ?></p>
    </div>
    &lt;?php
}

function myfp_add_copyright_to_content( $content ) {
    if ( is_single() &amp;&amp; in_the_loop() &amp;&amp; is_main_query() ) {
        $copyright_text = &#039;<p><em>' . esc_html__( '本文版权归本网站所有，转载请注明出处。', 'my-first-plugin' ) . '</em></p>';
        $content .= $copyright_text;
    }
    return $content;
}

Atenção: cada função de tradução contém um segundo parâmetro.‘my-first-plugin’Isso é o que você definiu no cabeçalho do plugin.Text DomainÉ um identificador único usado para que o WordPress saiba a qual plugin esses strings pertencem.

Em seguida, você precisa especificar isso nas notas de cabeça do plugin.Domain Path(Isto é,/languagesColoque os arquivos de tradução (.po e .mo) dentro da pasta apropriada. Você pode usar ferramentas como o Poedit para criar e gerenciar esses arquivos.

Seguir as normas de segurança e de codificação.

A segurança é de extrema importância no desenvolvimento de plugins. Nunca confie nos dados inseridos pelos usuários. Ao processar qualquer informação proveniente deles…$_GET、$_POSTou$_REQUESTAntes de usar os dados, é necessário realizar a validação, a limpeza e a codificação (escapamento) deles.

O WordPress oferece uma vasta gama de funções para ajudá-lo:
* 验证（Validation）：检查数据是否符合预期格式（如is_email()）。
* 清理（Sanitization）：清除数据中的非法字符（如sanitize_text_field()， sanitize_email()）。
* 转义（Escaping）：在将数据输出到HTML、JavaScript或URL之前，确保其安全（如esc_html()， esc_js()， esc_url()）。

Além disso, ao operar diretamente o banco de dados, é essencial utilizar as classes de banco de dados do WordPress.$wpdbOs métodos fornecidos, como…$wpdb->prepare()来防止SQL注入攻击。

resumos

Através deste guia, você completou todo o processo de criação de um plugin WordPress funcional, do zero. Você aprendeu como configurar o ambiente de desenvolvimento, criar os arquivos básicos do plugin, utilizar ganchos (hooks) de ações (actions) e filtros (filters) para adicionar funcionalidades ao WordPress, bem como como aprimorar a qualidade e a usabilidade do plugin através de práticas de internacionalização e segurança. O núcleo do desenvolvimento de plugins reside na compreensão e no uso avançado do sistema de ganchos do WordPress, que oferece uma extensibilidade e flexibilidade incomparáveis. Lembre-se: comece com funcionalidades simples, faça iterações graduais e sempre priorize a segurança e a qualidade do código. Assim, você poderá criar plugins WordPress fortes e confiáveis.

Perguntas frequentes Perguntas frequentes

Um plugin deve ser colocado em uma pasta?

Não necessariamente. Um plugin muito simples, composto por um único arquivo, pode ser usado para realizar essa tarefa diretamente.plugin-name.phpColocar emwp-content/plugins/No diretório. No entanto, para qualquer plugin que contenha vários arquivos (como CSS, JS, imagens ou arquivos de idioma), é fortemente recomendado usar uma pasta separada para organizar todos os arquivos relacionados. Isso torna a estrutura mais clara e facilita o gerenciamento.

Como criar uma página de configurações para o meu plugin?

Você pode usar a API de configurações fornecida pelo WordPress para criar páginas de configurações profissionais e seguras. Os passos principais incluem:add_menu_page()ouadd_submenu_page()A função registra uma página de menu e, em seguida, a utiliza.register_setting()、add_settings_section()eadd_settings_field()Use funções como `defineField` e `defineChapter` para definir os campos e capítulos. Por fim, escreva uma função de callback para gerar o formulário HTML da página de configurações.

No desenvolvimento de plugins, por que os prefixos são tão importantes?

O WordPress é um enorme ecossistema composto por plugins e temas. Todo o código é executado no mesmo espaço de nomes global. Se você definiu algo chamado…get_data()Se uma função comum já existir no código do site, e outro plugin também definir uma função com o mesmo nome, isso pode causar um erro fatal e levar o site a falhar. O uso de um prefixo único (como uma abreviação do nome do plugin) pode evitar esses conflitos significativamente, garantindo a compatibilidade entre os plugins.

Como devo depurar o código do meu plug-in?

No desenvolvimento com WordPress, a ferramenta preferida para depuração é a ativação do…WP_DEBUGVocê pode fazer isso no site.wp-config.phpNo arquivo, isso é feito através da configuração apropriada.define( ‘WP_DEBUG’, true );Para ativá-lo, basta seguir as instruções fornecidas. Isso fará com que todos os erros, avisos e notificações do PHP sejam exibidos na tela. Para um depuramento mais avançado, você pode utilizar outros recursos disponíveis.error_log()A função grava as informações no log de erros do servidor ou utiliza ferramentas de depuração PHP profissionais, como o Xdebug, em conjunto com o seu IDE, para realizar a depuração linha a linha.