A estrutura básica e a criação de plugins do WordPress

A estrutura básica e a criação de plugins do WordPress

Desenvolver um plugin para o WordPress começa com um simples arquivo PHP. Este arquivo principal deve conter comentários de cabeçalho específicos, para que o WordPress o reconheça e o possa gerenciar como um plugin. O plugin mais básico pode consistir em apenas um arquivo. my-first-plugin.php。

<?php
/**
 * Plugin Name: 我的第一个插件
 * Plugin URI:  https://example.com/my-first-plugin
 * Description: 这是一个用于演示的简单WordPress插件。
 * Version:     1.0.0
 * Author:      开发者姓名
 * License:     GPL v2 or later
 * Text Domain: my-first-plugin
 */

O “Nome do Plugin” nas notas do cabeçalho do arquivo é obrigatório; as outras informações são opcionais. Após o plugin ser ativado, suas funções são implementadas através da execução de funções PHP em momentos apropriados. Uma das maneiras mais comuns de fazer isso é usando “ganchos de ação” (action hooks). Por exemplo, para adicionar um texto no rodapé de uma página da web, você pode utilizar esses mecanismos. wp_footer Gancho.

// 在页脚输出自定义内容
function myplugin_add_footer_text() {
    echo '<p style="text-align:center;">Obrigado por usar o meu plugin!</p>';
}
add_action( 'wp_footer', 'myplugin_add_footer_text' );

add_action É uma função do núcleo do WordPress, usada para conectar funções personalizadas a ganchos de ação (action hooks) específicos. Geralmente, é recomendado colocar o diretório dos plugins em um local apropriado do sistema. /wp-content/plugins/your-plugin-name/ Além do arquivo principal, o diretório também pode conter arquivos de recursos como CSS, JavaScript, imagens, etc.

Leitura recomendada Guia definitivo para temas do WordPress: uma solução completa desde a seleção e personalização até o desenvolvimento.。

Como adicionar um menu de gerenciamento para um plugin?

Para que o plugin tenha uma página de configurações no painel administrativo do WordPress, você precisa adicionar um menu de gerenciamento para ele. Isso geralmente é feito através… admin_menu Isso é realizado através de ganchos de ação (action hooks).

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

função principal add_menu_page Usado para adicionar um item de menu principal na barra lateral do lado de trás, juntamente com a sua página de configurações correspondente.

function myplugin_add_admin_menu() {
    add_menu_page(
        '我的插件设置',      // 页面标题
        '我的插件',          // 菜单标题
        'manage_options',    // 所需权限
        'myplugin-settings', // 菜单slug
        'myplugin_settings_page', // 显示页面的回调函数
        'dashicons-admin-generic', // 图标（可选）
        6                    // 菜单位置（可选）
    );
}
add_action( 'admin_menu', 'myplugin_add_admin_menu' );

// 设置页面的HTML内容
function myplugin_settings_page() {
    ?>
    <div class="wrap">
        <h1></h1>
        <form action="/pt/options.php/" method="post" data-trp-original-action="options.php">
            <?php
            settings_fields( 'myplugin_options' ); // 输出安全字段
            do_settings_sections( 'myplugin-settings' ); // 输出设置区域
            submit_button(); // 输出提交按钮
            ?>
        <input type="hidden" name="trp-form-language" value="pt"/></form>
    </div>
    &lt;?php
}

Após criar o menu, o próximo passo é usar a API de configurações do WordPress para definir as opções específicas que podem ser configuradas.

Utilize a API de configurações para salvar as definições do plugin.

Tratar manualmente o envio de formulários e a verificação de segurança é um processo complicado e propenso a erros. A API de configurações do WordPress oferece um método padronizado para registrar, renderizar e salvar as configurações. Isso envolve principalmente três funções:register_setting, add_settings_section e add_settings_field。

O exemplo a seguir demonstra como registrar um grupo de opções e adicionar um campo de texto.

Leitura recomendada Guia de otimização de desempenho do site WordPress: análise aprofundada e estratégias práticas。

function myplugin_settings_init() {
    // 注册一个新的设置项到数据库 `wp_options` 表中
    register_setting( 'myplugin_options', 'myplugin_settings' );

    // 在设置页面添加一个新的区域
    add_settings_section(
        'myplugin_section_basic', // 区域ID
        '基础设置',                // 区域标题
        'myplugin_section_callback', // 区域说明的回调函数
        'myplugin-settings'       // 对应的页面slug
    );

    // 在区域中添加一个字段
    add_settings_field(
        'myplugin_field_text',    // 字段ID
        '示例文本',                // 字段标题
        'myplugin_field_text_cb', // 字段HTML输出的回调函数
        'myplugin-settings',      // 页面slug
        'myplugin_section_basic'  // 区域ID
    );
}
add_action( 'admin_init', 'myplugin_settings_init' );

// 区域说明的回调函数
function myplugin_section_callback() {
    echo '<p>Esta é a área de configurações básicas do plugin.</p>';
}

// 文本字段的回调函数
function myplugin_field_text_cb() {
    // 从数据库中获取之前保存的设置值
    $options = get_option( 'myplugin_settings' );
    $value = $options['myplugin_field_text'] ?? ''; // 使用空合并运算符提供默认值
    // 输出HTML输入框
    echo '<input type="text" name="myplugin_settings[myplugin_field_text]" value="' . esc_attr( $value ) . '" class="regular-text">'echo '<p class="description">Por favor, insira alguns exemplos de texto.</p>';
}

Os valores de configuração salvos dessa maneira podem ser utilizados em qualquer parte do código do plugin. get_option('myplugin_settings') Obter e usar de forma segura.

Segurança e boas práticas no desenvolvimento de plugins

A segurança é de extrema importância no desenvolvimento de plugins. Um plugin inseguro pode se tornar uma vulnerabilidade em todo o site. O princípio fundamental é: nunca confie nas informações fornecidas pelos usuários. Todos os dados provenientes de usuários ou de fontes externas devem ser verificados, limpos ou escapados (processados de forma a evitar erros) antes de serem inseridos no banco de dados, no sistema de arquivos ou exibidos nas páginas.

Validação e limpeza de dados

A validação é o processo de verificar se os dados inseridos seguem um formato esperado, como se são um endereço de e-mail, um número ou se estão dentro de um determinado intervalo. O WordPress disponibiliza uma série de funções auxiliares para isso. is_email(), absint()A limpeza consiste em remover, com base na verificação, quaisquer caracteres ilegais ou inseguros dos dados. Para campos de texto, isso pode ser feito utilizando métodos apropriados. sanitize_text_field()。

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

// 在处理表单提交时
$user_input = $_POST['some_field'] ?? ''; // 使用空合并运算符避免未定义索引警告
// 清理输入
$clean_input = sanitize_text_field( $user_input );
// 验证是否是正整数
$clean_id = absint( $_POST['post_id'] );
if ( $clean_id <= 0 ) {
    // 处理无效ID的错误
}

Dados de escape antes da saída.

A escape é o processo de garantir que os dados sejam exibidos de forma segura em diferentes contextos (como HTML, JavaScript, URLs). Isso é essencial para prevenir ataques de tipo Cross-Site Scripting (XSS). O WordPress disponibiliza funções de escape muito poderosas:
* esc_html(): É usado para escapar o conteúdo HTML, impedindo que os tags HTML presentes nele sejam interpretados (ou processados) pelo sistema.
* esc_attr()É usado para escapar os valores de atributos de etiquetas HTML.
* esc_url(): É usado para escapar URLs.
* wp_kses_post()Permite a saída segura de parte do HTML através de um conjunto de regras definido.

// 在设置页面或前端输出用户数据时
echo '<div class="notice">'`. esc_html($clean_input)`.'</div>'echo '<input type="hidden" value="' . esc_attr( $clean_input ) . '">'echo '<a href="/pt/' . esc_url( $user_url ) . '/">link</a>'echo wp_kses_post($allowed_html_content); // Permite o uso de etiquetas HTML no nível do artigo.

Além disso, ao lidar com consultas ao banco de dados, deve-se sempre utilizar as classes do banco de dados do WordPress. $wpdb Métodos de pré-processamento, ou o uso de APIs mais avançadas, como… WP_QueryElas possuem proteção contra injeções SQL integrada. Ao realizar operações com arquivos, utilize essa proteção. wp_upload_dir()、wp_handle_upload() Use APIs para garantir a segurança dos caminhos (paths).

Utilizando ganchos (hooks), é possível alcançar um alto nível de extensibilidade.

O núcleo do sistema de plugins do WordPress é o mecanismo de “ganchos” (hooks), que é composto por “ações” (actions) e “filtros” (filters). Os ganchos permitem que os plugins alterem o comportamento ou os dados do WordPress sem modificar o código principal, além de possibilitarem que outros desenvolvedores expandam o seu próprio plugin.

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

O uso e a criação de ganchos de ação (action hooks)

Os ganchos de ação (action hooks) executam um trecho de código em um ponto específico no tempo e não esperam um valor de retorno. Os plugins podem utilizar os milhares de ganchos internos fornecidos pelo WordPress. init, wp_enqueue_scripts, save_postÉ possível criar seus próprios “ganchos” (hooks) para que outros desenvolvedores possam usá-los.

O código montado no gancho é o seguinte:

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

// 在文章内容前自动添加一个横幅
function myplugin_prepend_content( $content ) {
    if ( is_single() ) {
        $custom_text = '<div class="myplugin-banner">Este é um espaço publicitário.</div>';
        $content = $custom_text . $content;
    }
    return $content;
}
add_filter( 'the_content', 'myplugin_prepend_content' );

Atenção: embora tenhamos modificado o conteúdo, estamos utilizando os ganchos (hooks) dos filtros. the_contentPorque ele exige que o valor modificado seja retornado.

Como criar um gancho (hook) para ações personalizadas do_action Função:

// 在你的插件代码中定义一个动作点
function myplugin_complete_task() {
    // ... 执行一些任务 ...
    // 发出自定义动作，允许其他代码在此处添加功能
    do_action( 'myplugin_after_task_complete', $task_id, $result );
}

Outros plugins ou temas podem ser adicionados através de… add_action('myplugin_after_task_complete', 'callback', 10, 2) Para responder a essa ação.

Princípios e exemplos dos ganchos de filtro (filter hooks)

Os ganchos de filtro (filter hooks) são utilizados para modificar os dados antes que eles sejam utilizados. Eles recebem um valor e devem retornar outro valor (que pode ter sido modificado). Esta é uma maneira comum de plugins alterarem o texto, as opções ou os resultados de consultas.

Use os filtros integrados:

// 修改文章摘要的长度
function myplugin_excerpt_length( $length ) {
    return 20; // 将摘要字数限制改为20字
}
add_filter( 'excerpt_length', 'myplugin_excerpt_length' );

Criar ganchos (hooks) para filtros personalizados apply_filters Função:

function myplugin_get_price( $product_id ) {
    $base_price = get_post_meta( $product_id, 'price', true );
    // 应用过滤器，允许其他代码动态修改价格（例如添加税费、折扣）
    $final_price = apply_filters( 'myplugin_product_price', $base_price, $product_id );
    return $final_price;
}

Dessa maneira, o seu plugin oferece uma interface flexível, permitindo que outros desenvolvedores modifiquem facilmente a lógica de cálculo dos preços sem a necessidade de alterar diretamente o código-fonte do seu plugin.

Internacionalização de plugins e gerenciamento de recursos de scripts

Um plugin WordPress maduro deve suportar a internacionalização, para que possa ser traduzido para diferentes idiomas, e deve gerenciar adequadamente os recursos CSS e JavaScript do lado front-end e do lado back-end.

Implementar a internacionalização de plugins

A internacionalização é realizada ao usar funções específicas para encapsular todas as strings de texto que precisam ser traduzidas. Isso envolve dois passos principais: carregar os arquivos de tradução usando campos de texto e marcar as strings que podem ser traduzidas no código.

Primeiramente, o que é definido no cabeçalho do arquivo principal do plugin… Text Domain(Por exemplo, my-first-plugin) Esse é o seu campo de texto. Em seguida, durante a inicialização do plugin (geralmente…) init (Gancho), use load_plugin_textdomain Uma função para carregar os arquivos de tradução.

function myplugin_load_textdomain() {
    load_plugin_textdomain(
        'my-first-plugin', // 文本域，必须与文件头一致
        false, // 已弃用参数
        dirname( plugin_basename( __FILE__ ) ) . '/languages' // 语言文件存放的相对路径
    );
}
add_action( 'init', 'myplugin_load_textdomain' );

No código, use… __() Vamos traduzir e retornar a string, usando: _e() para traduzir e produzir a string diretamente.

$settings_title = __( 'My Plugin Settings', 'my-first-plugin' );
_e( 'Hello World!', 'my-first-plugin' );

Os desenvolvedores podem usar isso. Poedit Ferramentas como essas extraem essas strings do código-fonte e as utilizam para gerar o resultado desejado. .pot Arquivo de modelo. .po e .mo O arquivo está armazenado no plugin. /languages/ No diretório.

Introduzir corretamente o CSS e o JavaScript

Nunca codifique valores diretamente em um arquivo PHP. <link> ou <script> Use tags para introduzir recursos. O WordPress disponibiliza um sistema unificado de enqueamento (enqueue) para gerenciar dependências de recursos, controle de versões e o momento de seu carregamento.

Para os recursos do backend, use… admin_enqueue_scripts Gancho.

function myplugin_admin_scripts( $hook ) {
    // 只在特定插件设置页面加载
    if ( $hook != 'toplevel_page_myplugin-settings' ) {
        return;
    }
    wp_enqueue_style(
        'myplugin-admin-style', // 句柄
        plugins_url( 'css/admin-style.css', __FILE__ ), // 文件URL
        array(), // 依赖
        '1.0.0'  // 版本号，可用于强制浏览器更新缓存
    );
    wp_enqueue_script(
        'myplugin-admin-script',
        plugins_url( 'js/admin-script.js', __FILE__ ),
        array( 'jquery' ), // 依赖jQuery
        '1.0.0',
        true // 在页脚加载
    );
}
add_action( 'admin_enqueue_scripts', 'myplugin_admin_scripts' );

Para os recursos front-end, use… wp_enqueue_scripts Os “ganchos” (hooks), cuja lógica é semelhante, garantem a ordem de carregamento dos recursos, evitam conflitos e permitem o uso do cache do navegador.

resumos

O desenvolvimento de plugins para o WordPress é um processo sistemático que começa com a criação de um arquivo principal que atenda aos padrões estabelecidos. Este processo abrange vários aspectos, como a construção da interface de administração, o tratamento seguro dos dados, o uso dos hooks do core do WordPress e o suporte à internacionalização. Seguir as melhores práticas, em especial as normas rigorosas de segurança de dados e um entendimento profundo do mecanismo de hooks, é fundamental para o desenvolvimento de plugins de nível comercial que sejam estáveis, seguros e escaláveis. O uso adequado da API de configurações e dos recursos de scripts de gestão pode melhorar significativamente a qualidade do plugin e a experiência do usuário. Os desenvolvedores devem sempre preparar o código para a tradução, a fim de expandir o alcance de aplicação do plugin.

Perguntas frequentes Perguntas frequentes

Quais elementos um plugin WordPress o mais simples precisa conter?

Um plugin muito simples requer apenas um arquivo PHP, e esse arquivo deve conter as anotações padrão de cabeçalho de um plugin. A linha de anotação mais importante é “Plugin Name”. Nesse arquivo, você pode escrever código PHP diretamente ou adicionar funcionalidades através de “ganchos” (hooks).

Por exemplo, um plugin que contém apenas um código curto que exibe a mensagem “Hello World” também precisa de apenas um arquivo para funcionar.

Como os plugins interagem com o banco de dados do WordPress?

Recomenda-se o uso das classes de operação de banco de dados integradas ao WordPress. $wpdbEle oferece métodos seguros para a consulta de dados, especialmente o seu… prepare Este método pode prevenir efetivamente ataques de injeção de SQL.

Para a maioria das operações com dados (como obter artigos ou manipular metadados), é mais recomendável utilizar as funções avançadas do WordPress. get_posts(), WP_Query, get_post_meta(), update_post_meta() Essas funções já cuidam dos problemas de segurança e cache no nível mais baixo do sistema. No caso de estruturas de dados personalizadas, os desenvolvedores podem criar tabelas de dados personalizadas quando o plugin for ativado.

Onde posso encontrar todos os ganchos (hooks) de ações e filtros disponíveis?

Os documentos oficiais de desenvolvimento do WordPress são o melhor local para encontrar os “ganchos” (hooks). Além disso, os desenvolvedores também podem procurar por esses ganchos diretamente no código-fonte do WordPress.

Abra o diretório raiz do WordPress no editor de código e faça uma busca. do_action ou apply_filters Ao chamar uma função, é possível encontrar todos os ganchos (hooks) definidos e seus parâmetros. Muitos materiais de referência online também compilam listas de ganchos mais comuns.

Como depurar o código do meu plugin do WordPress?

Primeiro, certifique-se de que em seu… wp-config.php O modo de depuração foi ativado no arquivo: define( 'WP_DEBUG', true );Isso permitirá a exibição de erros e avisos do PHP. Para evitar que as mensagens de erro sejam visíveis para os visitantes, é possível configurar isso simultaneamente. define( 'WP_DEBUG_DISPLAY', false ); E registre os erros num ficheiro de log:define( 'WP_DEBUG_LOG', true );。

Em segundo lugar, utilize error_log() A função registra informações de depuração personalizadas num ficheiro de log. No caso de estruturas de dados complexas (como arrays ou objetos), é possível utilizar métodos específicos para processar e gravar essas informações de forma eficiente. print_r() ou var_dump() As informações devem ser exibidas, mas somente após o login de um administrador, a fim de evitar a divulgação de dados. O uso de ferramentas profissionais de depuração em PHP, como o Xdebug, permite uma depuração mais eficiente com pontos de interrupção e rastreamento de pilha (stack trace).