Guia de Início para o Desenvolvimento de Plugins para WordPress

Guia de Início para o Desenvolvimento de Plugins para WordPress

Os plugins do WordPress são o mecanismo central para expandir as funcionalidades do núcleo do WordPress. Eles permitem que os desenvolvedores adicionem novas funcionalidades ao site ou modifiquem o comportamento existente sem alterar o código do núcleo do WordPress. Seja uma função simples de código curto ou um sistema de comércio eletrônico complexo, tudo pode ser implementado através de plugins. Compreender o funcionamento dos plugins é o primeiro passo para qualquer desenvolvedor de WordPress.

Um plugin para o WordPress é, essencialmente, um ou mais arquivos PHP que contêm código seguindo os padrões de codificação do WordPress. Esses arquivos são colocados em um diretório específico e interagem com o núcleo do WordPress através da API de plugins. Desenvolver plugins exige não apenas conhecimentos em PHP, mas também familiaridade com a vasta biblioteca de funções oferecida pelo WordPress, o sistema de ganchos (Hooks) e os métodos de operação do banco de dados.

Crie o seu primeiro arquivo de plugin.

Cada plugin do WordPress precisa de um arquivo principal, que serve como ponto de entrada para o plugin. Esse arquivo contém as informações metadadas do plugin e é responsável pela inicialização de suas funções essenciais.

Leitura recomendada Guia completo para o desenvolvimento de plugins do WordPress: do iniciante ao lançamento na loja.。

Estrutura do arquivo principal do plugin

O núcleo de um plugin é o arquivo principal, que geralmente recebe o nome do próprio plugin, por exemplo: my-first-plugin.phpAs notas de cabeça deste arquivo são de extrema importância, pois fornecem informações sobre a identidade do plugin para o WordPress. Uma nota de cabeça mínima para um arquivo principal é a seguinte:

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

O “Nome do Plugin” é um campo obrigatório; o WordPress utiliza esse nome para identificar e exibir o seu plugin na interface de gerenciamento do backend. Outras informações, como a versão do plugin e a descrição, ajudam os usuários a entenderem melhor as funcionalidades do mesmo.

Após definir as informações do plugin, geralmente começamos a adicionar o código das funcionalidades. Por exemplo, uma das funcionalidades mais simples é adicionar uma linha de texto personalizado na parte inferior do site. Isso pode ser feito utilizando… wp_footer Este gancho (Action Hook) é usado para implementar essa funcionalidade.

Implementar uma função de função simples

A seguir, um exemplo completo de arquivo principal de um plugin que implementa a funcionalidade de adicionar texto na parte inferior da página:

<?php
/**
 * Plugin Name: 页脚问候插件
 */
// 防止直接访问文件
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * 在网站页脚输出一条自定义问候语
 */
function myplugin_add_footer_text() {
	echo &#039;<p style="text-align:center;">Obrigado por visitar este site!</p>';
}
// 将函数挂载到`wp_footer`钩子上
add_action( 'wp_footer', 'myplugin_add_footer_text' );

Neste código,myplugin_add_footer_text É uma função que definimos nós mesmos; ela é responsável por realizar as operações de saída específicas (ou seja, por exibir os resultados desejados).add_action() É uma função do WordPress que permite “acoplar” (ou “hook”) nossas próprias funções aos componentes centrais do sistema WordPress. wp_footer No ponto de execução. Dessa forma, sempre que o WordPress chegar à parte do rodapé da página, nossa função será chamada automaticamente.

Leitura recomendada Do iniciante ao especialista: guia completo para o desenvolvimento de plugins do WordPress e tutoriais práticos.。

Compreender o mecanismo de ganchos (hooks) do WordPress

Os “ganchos” (Hooks) são o núcleo e a essência do desenvolvimento de plugins para o WordPress, pois permitem modificar ou expandir as funcionalidades padrão do sistema. Existem dois tipos principais de ganchos: os Ganchos de Ação (Action Hooks) e os Ganchos de Filtro (Filter Hooks).

Aplicação dos ganchos de ação (Action Hooks)

Os ganchos de ação (action hooks) permitem que você execute código personalizado em momentos específicos ou quando eventos ocorrem. Por exemplo, quando um artigo é publicado…publish_post), ou quando o usuário faz login (wp_loginUse. add_action() A função pode vincular sua função de callback a um gancho de ação (action hook).

Os exemplos abaixo demonstram como adicionar automaticamente uma declaração de direitos autorais após o conteúdo de um artigo:

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 myplugin_add_post_copyright( $content ) {
	if ( is_single() ) {
		$copyright = '<div class="post-copyright"><p>Este texto é de conteúdo original; por favor, indique a fonte ao reproduzi-lo.</p></div>';
		$content .= $copyright;
	}
	return $content;
}
add_filter( 'the_content', 'myplugin_add_post_copyright' );

Atenção, aqui usamos… add_filter() em vez de add_action()Isso porque modificar o conteúdo de um artigo é considerado um ato de “filtragem” dos dados. Isso levanta outro tipo de gancho (hook) importante.

Funções dos ganchos de filtro (Filter Hooks)

Os ganchos de filtro (filter hooks) permitem que você modifique os dados transmitidos durante o processo. A principal diferença em relação aos ganchos de ação (action hooks) é que as funções de filtro devem retornar um valor (geralmente o valor de entrada modificado). Por exemplo,the_content Os filtros permitem que você modifique o conteúdo dos artigos que serão exibidos., the_title Você pode modificar o título do artigo.

Os exemplos abaixo demonstram como usar filtros para alterar o comprimento de trechos de artigos:

Leitura recomendada Guia de Iniciação para Desenvolvimento de Plugins para WordPress: Construa o Seu Primeiro Plugin Personalizado do Zero。

function myplugin_custom_excerpt_length( $length ) {
	// 将默认的55个词改为20个词
	return 20;
}
add_filter( 'excerpt_length', 'myplugin_custom_excerpt_length' );

Neste exemplo, a nossa função… myplugin_custom_excerpt_length Recebemos o valor padrão para o comprimento do resumo e retornamos um novo valor que definimos. O WordPress usará esse novo valor para gerar o resumo.

Internacionalização de plugins e campos de texto

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 um conjunto completo de funções para realizar a tradução do plugin em vários idiomas.

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

Campo de texto para carregar o texto do plugin

O primeiro passo para a internacionalização é configurar corretamente o “Text Domain” nos plugins e carregar os arquivos de tradução no momento apropriado. O “Text Domain” deve ser exatamente o mesmo definido nas notas de cabeça do arquivo principal do plugin.

Geralmente, usamos isso durante a inicialização do plugin. load_plugin_textdomain Uma função para carregar as traduções. Uma prática padrão é colocar o seguinte código no arquivo principal:

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

Este código define uma função. myplugin_load_textdomainE use também… add_action Monte-o em… plugins_loaded No gancho. Isso garante que o arquivo de tradução seja carregado antes que o código funcional do plugin seja executado. O terceiro parâmetro especifica o caminho onde os arquivos de idioma (.mo) estão armazenados, geralmente no diretório do plugin. languages Na pasta.

Use a função de tradução para envolver a string.

No código do plugin, todas as strings direcionadas ao usuário que precisam ser traduzidas devem ser envolvidas em funções específicas. As duas funções mais comuns são: __() e _e()。

__() A função retorna a string traduzida. _e() A função simplesmente exibe o resultado (usando o comando `echo`). No exemplo anterior, em que adicionamos o texto do rodapé, deveríamos escrever o código da seguinte forma para suportar a tradução:

function myplugin_add_footer_text() {
	$text = __( '感谢您访问本网站！', 'my-first-plugin' );
	echo '<p style="text-align:center;">'`. esc_html($text)`.'</p>';
}
add_action( 'wp_footer', 'myplugin_add_footer_text' );

Aqui, a string “Obrigado por visitar este site!” foi… __() Função encapsulada, com a especificação do campo de texto. my-first-pluginOs tradutores podem criar arquivos de tradução para este texto em diferentes idiomas. Ao mesmo tempo, utilizamos… esc_html() A função realiza a escape dos dados de saída, o que é uma prática importante de segurança.

Segurança de plugins e melhores práticas

Desenvolver um plugin popular significa que a segurança e a qualidade do código devem ser tão importantes quanto as próprias funcionalidades do plugin. Seguir as melhores práticas de desenvolvimento pode proteger os sites dos usuários e aumentar a confiabilidade e a manutenibilidade do plugin.

Validação de dados, escape e limpeza

Nunca confie em dados provenientes de usuários ou de fontes externas. Antes de processar qualquer dado recebido (como $_GET, $_POST, $_COOKIE) ou de exibi-lo no navegador ou em um banco de dados, é necessário realizar verificações apropriadas.

Para os dados exibidos em uma página HTML, é recomendável usar as funções de escape do WordPress. esc_html(), esc_attr(), esc_url()Para os dados que serão armazenados no banco de dados, use… wp_strip_all_tags() ou sanitize_text_field() Faça a limpeza. O exemplo abaixo mostra uma maneira segura de processar os dados inseridos em um formulário:

// 假设我们接收一个名为`user_bio`的POST字段
$raw_bio = $_POST['user_bio'] ?? ''; // 使用空合并运算符提供默认值
// 清理数据：移除标签，清理额外空格和特殊字符
$clean_bio = sanitize_textarea_field( $raw_bio );
// 在存入数据库前，还可以使用`wp_kses_post`允许安全的HTML标签
$safe_bio_for_db = wp_kses_post( $clean_bio );
// 现在$safe_bio_for_db可以安全地存入数据库了

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

Se o seu plugin possui uma interface de gestão ou é responsável pelo processamento de submissões de formulários, é necessário utilizar o mecanismo “nonce” (Número usado uma única vez) do WordPress para evitar ataques de falsificação de solicitações entre sites (CSRF – Cross-Site Request Forgery). Além disso, é essencial realizar verificações de capacidades (Capability Checks) para garantir que o usuário atual tenha as permissões necessárias para executar a operação.

Ao criar um menu de gerenciamento ou um formulário, gere um campo que não seja do tipo “CE” (Common Elements).

// 在表单中输出一个非ce字段
wp_nonce_field( 'myplugin_save_action', 'myplugin_nonce_field' );

Ao processar o envio de um formulário, é necessário verificar se o campo “non-ce” contém um valor válido.

// 验证非ce
if ( ! isset( $_POST['myplugin_nonce_field'] ) || ! wp_verify_nonce( $_POST['myplugin_nonce_field'], 'myplugin_save_action' ) ) {
	wp_die( __( '安全校验失败，操作已终止。', 'my-first-plugin' ) );
}
// 检查用户权限（例如，检查是否有`manage_options`权限）
if ( ! current_user_can( 'manage_options' ) ) {
	wp_die( __( '您没有执行此操作的权限。', 'my-first-plugin' ) );
}
// 通过所有安全检查，开始处理数据...

Seguir essas diretrizes de segurança é a base para criar um plugin confiável.

resumos

O desenvolvimento de plugins para o WordPress é um processo que transforma ideias em funcionalidades reais, e isso só é possível com um profundo entendimento da arquitetura central do WordPress. Tudo começa com a criação de um arquivo principal que contenha as devidas anotações de cabeçalho (header comments). Ao dominar as diferenças e o uso dos “action hooks” e “filter hooks”, os desenvolvedores podem expandir as funcionalidades do sistema. A internacionalização dos plugins permite que seus produtos atendam a usuários de todo o mundo. Práticas de segurança consistentes, como validação de dados, escape de caracteres, limpeza de dados e verificações de permissões, são a base para garantir a estabilidade e a confiabilidade dos plugins, além de conquistar a confiança dos usuários. Seguindo esses passos e as melhores práticas, você será capaz de criar plugins para o WordPress que sejam poderosos, seguros e fáceis de manter.

Perguntas frequentes Perguntas frequentes

Um plugin para WordPress precisa de no mínimo quantos arquivos?

Um plugin do WordPress com a funcionalidade mais simples pode conter apenas um arquivo PHP. Este arquivo deve conter as notas de cabeça padrão para plugins (como o “Nome do Plugin”, entre outras), além do código responsável pela implementação da funcionalidade desejada. À medida que as funcionalidades do plugin se tornam mais complexas, ele geralmente é dividido em vários arquivos, que também podem incluir ficheiros CSS, JavaScript, imagens e ficheiros de tradução para diferentes idiomas.

Devo escrever o código do plugin diretamente no arquivo functions.php do tema?

Para o código que é específico apenas para o tópico atual e tem funções intimamente relacionadas, ele pode ser escrito dentro do próprio tópico.functions.phpCerto. No entanto, para funcionalidades que sejam universais e possam ser utilizadas em diferentes temas, é fortemente recomendado que sejam desenvolvidas como plugins independentes. A vantagem dos plugins é que eles são independentes dos temas; portanto, a funcionalidade não é perdida ao trocar de tema, o que também facilita a sua gestão e distribuição.

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

Você pode usar as funções fornecidas pelo WordPress para adicionar menus de gerenciamento e páginas. As mais comuns são… add_menu_page() ou add_options_page() Você precisa criar uma função de callback para exibir o conteúdo HTML da página e processar o envio do formulário (incluindo a verificação de segurança “CE” e a verificação de permissões). Geralmente, esse processo envolve o uso da API de Configurações do WordPress (Settings API), que pode ajudar a criar e gerenciar opções de configuração de maneira mais padronizada e segura.

Ao desenvolver plugins, como depurar e registrar erros?

Primeiramente, assegure-se de que, no ambiente de desenvolvimento…wp-config.phpAtivar WP_DEBUG no arquivo:define( 'WP_DEBUG', true );Isso exibirá erros e avisos do PHP na página. Para um depuramento mais avançado, é possível utilizar…error_log()A função registra as informações no log de erros do servidor ou utiliza os recursos do WordPress para isso.wp_debugFunções relacionadas. Além disso, existem muitos plugins de depuração de terceiros de excelente qualidade, como o Query Monitor, que podem ajudá-lo a analisar consultas ao banco de dados, ganchos (hooks) e scripts, sendo verdadeiros auxiliares no desenvolvimento de plugins.