Analisi dei funzioni e dei metodi indispensabili

Nello sviluppo di WordPress, il successo o il fallimento di un plugin dipende spesso dall’efficace utilizzo delle potenti funzioni fornite dal nucleo di WordPress stesso. In questo capitolo ci concentreremo su alcuni degli API più importanti e più frequentemente utilizzati dai plugin, analizzando in dettaglio i loro contesti di utilizzo, i parametri e i metodi disponibili, al fine di aiutare gli sviluppatori a creare plugin stabili, efficienti e facili da mantenere.

Funzioni di hook per le azioni principali e i filtri

L’architettura dei plugin di WordPress si basa su un sistema di “hook” (ganci), che consente agli sviluppatori di inserire funzionalità personalizzate in momenti specifici dell’esecuzione del codice di base del sito. Comprendere e utilizzare correttamente queste funzioni di hook rappresenta il primo passo nell’ambito dello sviluppo di plugin.

Montare funzionalità personalizzate nel flusso di lavoro principale di WordPress

Le funzionalità degli plugin devono essere attivate nel momento giusto, e questo avviene solitamente tramite il meccanismo delle “azioni” (actions) di WordPress.add_action Le funzioni rappresentano il ponte che collega i plugin al ciclo di vita principale del sistema; consentono agli sviluppatori di eseguire codice personalizzato quando specifici eventi si verificano. remove_action Viene utilizzato per rimuovere le azioni che sono state già montate (ovvero eseguite).

Si consiglia di leggere Guida all’approccio di base allo sviluppo di plugin per WordPress: crea il tuo primo plugin da zero。

La sintassi di base è la seguente:

UltaHost – Hosting per siti WordPress

Garanzia di rimborso entro 30 giorni, larghezza di banda illimitata e accesso ai database, protezione gratuita contro gli attacchi DDoS; sconto del 50% per l’acquisto di un piano valido per 3 anni (da 3 a 4 TB di spazio di archiviazione).

pagina di accesso

add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 )

Ad esempio, inviare un’e-mail di notifica dopo la pubblicazione del contenuto di un articolo:

function send_post_notification( $post_id ) {
    // 发送邮件的逻辑
}
add_action( 'publish_post', 'send_post_notification' );

add_action Il parametro di priorità determina l’ordine di esecuzione di più callback all’interno dello stesso “hook”; più il numero è basso, più il callback viene eseguito per primo. Questo è di fondamentale importanza per i plugin complessi che richiedono il controllo dell’ordine di esecuzione delle operazioni.

Modificare i dati trasmessi ad altre funzioni o l’output prodotto da esse.

Oltre ad eseguire il codice in momenti specifici, i sviluppatori hanno spesso bisogno di modificare i dati generati da altre funzioni; in questi casi è necessario utilizzare i “filter hooks”.add_filter La funzione è utilizzata per aggiungere un callback di filtraggio; riceve i dati in ingresso, li modifica e deve restituire i dati modificati.

Ad esempio, modificare l’ultimo carattere di tutti i titoli degli articoli:

Si consiglia di leggere Maestri questi hook e filtri di WooCommerce e personalizza le funzionalità del tuo sito e-commerce.。

function modify_post_title( $title ) {
    return $title . ' - 我的网站';
}
add_filter( 'the_title', 'modify_post_title' );

与 add_action Allo stesso modo…add_filter Sono anche supportati l’impostazione della priorità e del numero di parametri. I filtri rappresentano la base su cui WordPress può essere ulteriormente personalizzato.

Funzioni per l’operazione sui database e la gestione delle opzioni

I plugin di solito necessitano di un sistema di archiviazione dei dati in modo persistente (cioè che i dati vengano conservati anche dopo la chiusura del browser o del sito web). WordPress fornisce un API per la gestione dei dati strutturata, che va dalle semplici opzioni di configurazione del sito fino alle operazioni più complesse su tabelle di database personalizzate.

Stocare e recuperare in modo sicuro le impostazioni dei plugin

Per i plugin che richiedono la salvaguardia delle impostazioni degli utenti, è necessario memorizzare le opzioni di configurazione nel database di WordPress.add_option、get_option 和 update_option Costituiscono la base della gestione dei dati. Queste funzioni operano su… wp_options Tabelle sono adatte per l’archiviazione di dati di tipo chiave-valore relativamente semplici.

hosting.com Hosting condiviso

Prestazioni elevate con CPU AMD EPYC, storage SSD NVMe e LiteSpeed, supporto interno di esperti 24 ore su 24, 7 giorni su 7, misure di sicurezza avanzate, tra cui SSL, brute force, malware e protezione DDoS, risparmi fino a 73%

pagina di accesso

Innanzitutto, è possibile utilizzare… add_option Per aggiungere un valore iniziale… wp_options La funzione inserisce i dati soltanto quando l’opzione non esiste.

add_option( 'my_plugin_api_key', '', '', 'no' ); // ‘no’表示非自动加载

Per ottenere il valore di un’opzione, si utilizza… get_optionSi consiglia di fornire sempre dei valori predefiniti.

$api_key = get_option( 'my_plugin_api_key', '' ); // 第二个参数为默认值

Per aggiornare i valori delle opzioni, utilizzare… update_optionSe l’opzione non esiste, verrà creata automaticamente.

Si consiglia di leggere Guida definitiva allo sviluppo di plugin per WordPress: costruire estensioni professionali da zero。

update_option( 'my_plugin_api_key', 'new_secret_key_123' );

Per i dati complessi, come array o oggetti, che necessitano di essere memorizzati, queste funzioni eseguono automaticamente l’serializzazione e la deserializzazione.

Eseguire una query personalizzata al database

Quando un plugin ha bisogno di memorizzare dati relazionali o log, creare tabelle di database personalizzate è solitamente la scelta migliore. In questo caso, è necessario interagire direttamente con le classi di astrazione del database di WordPress. $wpdb L’interazione fornisce un modo sicuro e standardizzato per accedere ai database.

Hosting condiviso InterServer

Hosting condiviso $2,50 USD al mese, primo mese $0,1 USD codice promozionale tryinterserver, 461 script di applicazioni cloud, installazione con un clic.

pagina di accesso

Innanzitutto, creare un tabellone all’interno del hook di attivazione del plugin. Assicurarsi di utilizzare… dbDelta La funzione permette di creare o aggiornare in modo sicuro la struttura di un database, confrontando le differenze tra la struttura attuale e quella desiderata e applicando automaticamente i cambiamenti necessari in modo intelligente.

global $wpdb;
$table_name = $wpdb->prefix . 'my_plugin_orders';
$charset_collate = $wpdb->get_charset_collate();
$sql = "CREATE TABLE $table_name (
    id bigint(20) NOT NULL AUTO_INCREMENT,
    customer_email varchar(100) NOT NULL,
    amount decimal(10,2) NOT NULL,
    order_date datetime DEFAULT CURRENT_TIMESTAMP NOT NULL,
    PRIMARY KEY (id),
    KEY customer_email (customer_email)
) $charset_collate;";
require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
dbDelta( $sql );

Quando si esegue una query sui dati, è necessario utilizzare… $wpdb->prepare Eseguire la preparazione delle istruzioni in modo appropriato è fondamentale per prevenire gli attacchi di iniezione SQL:

$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->prefix}my_plugin_orders WHERE order_date > %s AND amount > %f",
        '2026-01-01 00:00:00',
        100.00
    )
);

Funzione di generazione e output di contenuti

I plugin non solo possono essere eseguiti in background, ma cosa più importante, sono in grado di generare contenuto per i visitatori. WordPress offre funzionalità potenti per generare HTML in modo sicuro e flessibile, gestire i codici brevi (shortcodes) e gestire i file statici.

Inserire contenuto dinamico in articoli e pagine

I codici brevi permettono agli utenti di inserire contenuto dinamico negli articoli e sulle pagine utilizzando semplici tag, rappresentando una funzionalità fondamentale per migliorare l’usabilità dei plugin. add_shortcode È possibile creare facilmente propri frammenti di codice corto (chiamati “funzioni”).

add_shortcode La funzione accetta due parametri: un tag di codice breve e una funzione di elaborazione. La funzione di elaborazione deve restituire il contenuto HTML, anziché visualizzarlo direttamente, in conformità con il principio di WordPress che prevede di “catturare i dati prima di renderizzarli”.

add_shortcode( 'recent_posts', 'my_plugin_render_recent_posts' );
function my_plugin_render_recent_posts( $atts ) {
    // 解析属性，设置默认值
    $attributes = shortcode_atts( array(
        'count' => 5,
        'category' => ''
    ), $atts );

// 根据属性查询文章逻辑...
    $output = '<ul class="recent-posts">';
    // ... 生成列表项
    $output .= '</ul>';
    return $output;
}

Gli utenti devono semplicemente inserire i contenuti nell’editor. [recent_posts count="3"] A questo punto verrà visualizzata l’elenco degli articoli più recenti.

Stampare i valori delle variabili in modo sicuro nell’HTML

Quando un plugin ha bisogno di visualizzare variabili sul sito web (ad esempio, testo ottenuto da un database o impostazioni configurate), basta utilizzarle direttamente. echo L’incorporamento di stringhe può comportare rischi di attacchi tipo Cross-Site Scripting (XSS). WordPress fornisce funzioni di escape apposite per garantire la sicurezza degli output.

Per l’output all’interno degli attributi delle tag HTML, si utilizza… esc_attr Funzione:

echo '<input type="text" value="' . esc_attr( get_option( 'site_title' ) ) . '">';

Per l’output all’interno del contenuto delle tag HTML, utilizzare… esc_html：

\necho '<h1>'`. esc_html($post_title)`.'</h1>';

Per i contenuti HTML che sono stati già verificati come sicuri (ad esempio, quelli che hanno superato i test di sicurezza necessari)... wp_kses_post Per filtrare i contenuti, è necessario utilizzare un’apposita tecnologia. Tuttavia, per ottenere l’URL completo dei risultati, è possibile ricorrere a strumenti o metodi specifici. esc_url：

\necho '<a href="/it/' . esc_url( $external_link ) . '/">link (su un sito web)</a>';

Per visualizzare le variabili PHP all'interno di un blocco di codice JavaScript, è necessario utilizzare wp_json_encode E in coordinamento con… esc_js：

<script>
var pluginSettings = <?php echo wp_json_encode( $settings_array ); ?>;
var message = '<?php echo esc_js( $user_message ); ?>';
</script>

Funzioni per l’elaborazione di file e media

Molti plugin si occupano di caricamento di file, elaborazione di immagini o accesso ai file presenti all’interno di temi o altri plugin. WordPress nasconde la complessa logica relativa ai percorsi server e ai URL, offrendo un insieme di API semplici da utilizzare.

Ottenere il percorso assoluto dei risorse interne di un plugin o di un tema.

Nello sviluppo di plugin, è spesso necessario fare riferimento a file CSS, JavaScript o immagini presenti nel proprio stesso directory. L’utilizzo di percorsi assoluti codificati in modo statico rappresenta un rischio significativo per la sicurezza, poiché il sito potrebbe essere spostato (migrato) in un ambiente diverso. WordPress offre soluzioni per gestire in modo sicuro questi riferimenti, permettendo di modificare facilmente i percorsi senza dover modificare il codice sorgente del plugin stesso. plugin_dir_path 和 plugins_url Esiste una funzione che permette di generare dinamicamente i percorsi.

plugin_dir_path Restituisce la path del file system del server che contiene la directory dei plugin, con una barra (/) alla fine; adatta per… include 或 require File:

$config_path = plugin_dir_path( __FILE__ ) . 'config/config.php';
if ( file_exists( $config_path ) ) {
    require_once $config_path;
}

而 plugins_url Viene utilizzato per generare URL accessibili tramite il browser, adatti all’uso in…

或 Riferimenti a risorse presenti all’interno del testo:

$css_url = plugins_url( 'assets/css/admin-style.css', __FILE__ );
wp_enqueue_style( 'my-admin-style', $css_url );

Per i sviluppatori di temi, la funzione corrispondente è… get_template_directory_uri 和 get_stylesheet_directory_uri。

Trattamento dei file multimediali caricati dagli utenti

Se il plugin consente agli utenti di caricare file, non è assolutamente possibile utilizzarli direttamente. $_FILES Global arrays move_uploaded_file Funzioni: Le funzioni di elaborazione dei media in WordPress wp_handle_upload È stata fornita un’interazione completa tra i controlli di sicurezza e la gestione dei file.

Questa funzione gestisce automaticamente i controlli sui tipi di file, i processi di rinominazione (per evitare sovrascritture), nonché l’elaborazione degli errori; inoltre, sposta i file all’interno della struttura di directory del catalogo multimediale di WordPress.

$uploadedfile = $_FILES['my_plugin_upload'];
$upload_overrides = array( 'test_form' => false );
$movefile = wp_handle_upload( $uploadedfile, $upload_overrides );

if ( $movefile && ! isset( $movefile['error'] ) ) {
    // 文件上传成功
    $file_url = $movefile['url'];
    $file_path = $movefile['file'];
    // 可以将 $file_url 存入数据库
} else {
    // 上传失败，输出错误信息
    echo $movefile['error'];
}

Per integrare ulteriormente i file caricati nel catalogo multimediale di WordPress, è possibile utilizzare anche… wp_insert_attachment La funzione crea post con allegati, permettendo così di utilizzare le funzionalità di elaborazione delle immagini integrate in WordPress (ad esempio, la creazione di miniature).

Riassumendo

Conoscere le funzioni e i metodi fondamentali di WordPress rappresenta la base per lo sviluppo di plugin e temi in modo efficiente e sicuro. Partiamo dal sistema di hook (…)add_action, add_filterImplementare un approccio modulare per le operazioni sul database.$wpdb, get_optionAssicurarsi che i dati vengano conservati in modo permanente, per poi procedere con l’output del contenuto.add_shortcode, esc_html) e la gestione sicura (wp_handle_uploadOgni insieme di funzioni fornisce soluzioni collaudate per scenari specifici. Gli sviluppatori dovrebbero comprendere a fondo i parametri, i valori restituiti e le migliori pratiche di utilizzo di tali funzioni, per evitare di reinventare soluzioni già esistenti o di introdurre vulnerabilità di sicurezza, al fine di creare estensioni per WordPress sia potenti che affidabili.

FAQ - Domande frequenti

Qual è la differenza fondamentale tra `add_action` e `add_filter`?

La principale differenza tra i due consiste nell’uso e nel comportamento previsto delle funzioni di callback.add_action Viene utilizzato per “eseguire un’azione” quando un determinato evento si verifica; la funzione di callback associata di solito non restituisce alcun valore, ma si limita ad eseguire un insieme di operazioni logiche (ad esempio, inviare un’e-mail o registrare un evento nel log). add_filter Vengono utilizzati per “modificare un determinato dato”; la funzione di callback deve ricevere un valore in input e restituire il valore modificato. Dal punto di vista dell’implementazione tecnica, sono essenzialmente identici, ma la distinzione semantica rende il codice più leggibile.

Perché, quando si utilizza la classe $wpdb, è obbligatorio utilizzare il metodo prepare?

$wpdb->prepare I metodi rappresentano la linea di difesa fondamentale contro gli attacchi di iniezione SQL. Essi ricevono i valori delle variabili utilizzando dei placeholder (%s per le stringhe, %d per gli interi, %f per i numeri in virgola mobile) e garantiscono che tali valori vengano correttamente escapeati e formattati prima di essere inseriti nelle istruzioni SQL. Anche se si è certi che la fonte delle variabili sia sicura (ad esempio, proveniente da fonti affidabili… get_option(), utilizzando prepare È anche una buona abitudine da seguire, poiché permette di garantire che il codice rimanga stabile anche di fronte a futuri cambiamenti o situazioni complesse.

Le funzioni `esc_html` e `esc_attr` possono essere utilizzate in modo intercambiabile?

Anche se in alcuni casi semplici lo scambio tra le due funzioni potrebbe non causare errori immediati, si sconsiglia vivamente di farlo. Queste due funzioni sono state ottimizzate per contesti HTML diversi.esc_html Utilizzato per escapare il contenuto all’interno dei tag HTML; permette di evitare problemi legati all’interpretazione errata del codice. <、>、&、"、' I caratteri come “”, “&”, “<”, “>”, “&”, “"”, “'” vengono convertiti in entità HTML. esc_attr È un strumento specificamente progettato per escapare i valori presenti all’interno degli attributi degli elementi HTML, tenendo conto anche del contesto in cui tali valori potrebbero essere racchiusi tra virgolette. L’utilizzo della funzione corretta garantisce che gli escape avvengano in modo sicuro in tutte le situazioni possibili.

Qual è il significato della costante FILE presente in `plugin_dir_path(FILE)`?

FILE Si tratta di una costante magica in PHP che rappresenta l’intero percorso e il nome del file in cui viene eseguito lo script attuale, all’interno del file system. Deve essere utilizzata nel file principale del plugin. plugin_dir_path(FILE)È possibile ottenere in modo dinamico e preciso il percorso assoluto della directory del plugin, indipendentemente da dove sia installato. Questo è molto più affidabile rispetto all’uso di percorsi fissi (hardcoded), poiché garantisce la portabilità del plugin in diversi ambienti di server. Nello sviluppo di temi (temi per siti web), esistono costanti simili che permettono di gestire in modo analogo queste informazioni. DIR o funzione get_template_directory() Svolgono lo stesso ruolo.