Sviluppo di plugin WordPress per principianti

Introduzione allo sviluppo di plugin WordPress

I plugin WordPress sono componenti aggiuntivi modulari che estendono le funzionalità di WordPress senza modificare il codice del core. Con oltre 60.000 plugin nel repository ufficiale di WordPress, l'ecosistema dei plugin è uno dei motivi principali per cui WordPress è il CMS più utilizzato al mondo. Sviluppare i propri plugin ti dà il controllo completo sulle funzionalità del sito e ti consente di creare soluzioni perfettamente su misura per le esigenze dei tuoi clienti o della tua attività.

Per iniziare a sviluppare un plugin WordPress ti servono un ambiente di sviluppo locale o un hosting con WordPress installato, conoscenze di PHP da livello base a intermedio e la comprensione dell'architettura di WordPress, in particolare del sistema degli hook. Strumenti come Local by Flywheel, XAMPP o Docker facilitano la configurazione di un ambiente locale per lo sviluppo e il test dei plugin prima della pubblicazione in produzione.

Struttura di un plugin WordPress

Ogni plugin WordPress parte da un singolo file PHP con un commento speciale nell'intestazione che indica a WordPress che si tratta di un plugin. Questo commento contiene il nome del plugin, la descrizione, la versione, l'autore e altri metadati. WordPress scansiona la directory wp-content/plugins e legge questi header per mostrare l'elenco dei plugin disponibili nel pannello di amministrazione.

Struttura minima di un plugin

Il plugin più semplice è un singolo file PHP nella directory wp-content/plugins con un header corretto. Tuttavia, per un plugin più serio è consigliata un'organizzazione in una directory dedicata con file principale, directory includes per le classi helper, directory admin per le pagine di amministrazione, directory public per il codice frontend e directory assets per i file CSS e JavaScript.

• plugin-name/plugin-name.php - file principale del plugin con header e inizializzazione
• plugin-name/includes/ - classi PHP e funzioni helper
• plugin-name/admin/ - pagine admin, impostazioni, metabox
• plugin-name/public/ - funzionalità frontend e template
• plugin-name/assets/css/ - stili CSS per admin e frontend
• plugin-name/assets/js/ - file JavaScript
• plugin-name/languages/ - file di localizzazione e traduzione
• plugin-name/templates/ - template HTML che il tema può sovrascrivere

Usa namespace o prefissi per tutte le funzioni. Consulta la guida alla sicurezza del sito per ulteriori suggerimenti e classi per evitare conflitti con altri plugin. Ad esempio, invece del generico get_settings() usa beo_plugin_get_settings() o, meglio ancora, il namespace PHP BeoPlugin e le classi. Questo è cruciale perché WordPress carica tutti i plugin attivi nello stesso scope PHP e i conflitti di naming portano a fatal error.

Sistema degli hook di WordPress

Il sistema degli hook è il cuore dell'architettura di WordPress e comprendere gli hook è assolutamente essenziale per lo sviluppo di plugin. WordPress definisce centinaia di hook nei punti chiave del processo di esecuzione del codice, e i plugin si agganciano a questi per eseguire il proprio codice al momento giusto. Esistono due tipi di hook: action e filter.

Action

Le action sono hook che ti permettono di eseguire codice in un punto specifico del processo di WordPress. Ad esempio, l'action init si attiva dopo che WordPress ha completato il caricamento ma prima di inviare qualsiasi output, wp_enqueue_scripts si attiva quando occorre aggiungere file CSS e JS, e save_post si attiva quando un post viene salvato. Usa la funzione add_action() per registrare la tua funzione di callback su uno specifico hook di tipo action.

Filter

I filter sono hook che ti permettono di modificare i dati prima che WordPress li utilizzi o li visualizzi. Una funzione di callback di tipo filter riceve un valore, lo modifica e restituisce la versione modificata. Ad esempio, il filter the_content ti permette di modificare il contenuto del post prima della visualizzazione, the_title modifica il titolo, e il filter wp_mail consente di modificare i messaggi email prima dell'invio. Usa add_filter() per registrare i callback dei filter.

• add_action('hook_name', 'callback', priority, args) - registra una funzione su un hook di tipo action
• add_filter('hook_name', 'callback', priority, args) - registra una funzione su un hook di tipo filter
• do_action('custom_hook') - crea un tuo hook di tipo action che altri plugin possono usare
• apply_filters('custom_filter', $value) - crea un tuo hook di tipo filter
• remove_action() / remove_filter() - rimuove una funzione registrata in precedenza

Il parametro priority (predefinito 10) determina l'ordine di esecuzione quando più funzioni sono registrate sullo stesso hook. Un numero più basso significa esecuzione anticipata. Questo è utile quando vuoi che il tuo codice venga eseguito prima o dopo il codice di un altro plugin sullo stesso hook. Definisci sempre esplicitamente la priority se l'ordine di esecuzione è importante, perché il valore predefinito può portare a risultati imprevedibili.

Creazione di pagine admin

La maggior parte dei plugin richiede pagine admin per configurare le impostazioni. WordPress fornisce le Settings API per creare pagine di impostazioni che si integrano con il pannello di amministrazione di WordPress. Usa add_menu_page() per aggiungere una voce di menu principale oppure add_submenu_page() per aggiungere una sottopagina sotto una voce di menu esistente.

Settings API

Le Settings API di WordPress automatizzano l'archiviazione e la validazione delle impostazioni utilizzando la tabella delle options di WordPress. Registri le impostazioni con register_setting(), definisci le sezioni con add_settings_section() e i campi con add_settings_field(). WordPress genera quindi automaticamente il form, archivia i dati e applica la sanitizzazione. È un approccio più sicuro rispetto alla gestione manuale delle richieste POST, perché le Settings API aggiungono automaticamente la verifica del nonce e il controllo dei permessi dell'utente.

Per interfacce admin più complesse, puoi usare pagine admin personalizzate con il tuo HTML e JavaScript invece delle Settings API. In tal caso, usa gli hook wp_ajax_ per le chiamate AJAX e assicurati di aggiungere la verifica del nonce con wp_nonce_field() e check_admin_referer() per la protezione dagli attacchi CSRF. Verifica inoltre i permessi dell'utente con current_user_can() all'inizio di ogni pagina admin e di ogni handler AJAX.

Esempio di menu admin

In pratica, la creazione di una pagina admin richiede due passaggi. Primo, registra la voce di menu sull'hook admin_menu usando add_menu_page con i parametri per titolo della pagina, titolo del menu, permesso richiesto (di solito manage_options per gli amministratori), slug della pagina, funzione di callback che renderizza l'HTML e, facoltativamente, un'icona. Poi, nella funzione di callback, genera la pagina HTML con un form usando settings_fields() e do_settings_sections() per il rendering automatico delle impostazioni registrate.

Creazione di shortcode

Gli shortcode permettono agli utenti di incorporare le funzionalità del tuo plugin direttamente nel contenuto di post e pagine utilizzando tag brevi tra parentesi quadre. Registra uno shortcode con la funzione add_shortcode(), che prende il nome dello shortcode e una funzione di callback. Il callback riceve gli attributi specificati dall'utente, il contenuto compreso tra i tag di apertura e chiusura e il nome dello shortcode stesso.

Esempio di implementazione

Immagina di creare un plugin per mostrare i membri del team. Lo shortcode [team_member name="Marco" role="Developer" photo="url"] mostrerebbe una card stilizzata con foto, nome e ruolo del membro del team. La funzione di callback riceve l'array $atts, usa shortcode_atts() per definire i valori predefiniti e restituisce una stringa HTML con la visualizzazione formattata. Non usare mai echo nel callback di uno shortcode, ma restituisci sempre una stringa, perché echo altera l'ordine di visualizzazione dei contenuti nella pagina.

• Shortcode self-closing - [button text="Clicca" url="/link"] - senza contenuto in mezzo
• Shortcode enclosing - [highlight]testo importante[/highlight] - ha contenuto tra i tag
• Shortcode annidati - do_shortcode($content) nel callback per il supporto all'annidamento

Attivazione, disattivazione e disinstallazione

WordPress fornisce tre hook per gli eventi del ciclo di vita del plugin. register_activation_hook() viene chiamato quando l'utente attiva il plugin e lì di solito crei le tabelle del database, imposti le impostazioni predefinite e registri le attività cron. register_deactivation_hook() viene chiamato alla disattivazione e lì ripulisci timer e dati temporanei, ma lasci i dati perché l'utente potrebbe riattivare il plugin.

Per l'eliminazione permanente dei dati alla disinstallazione, usa register_uninstall_hook() oppure il file uninstall.php nella directory principale del plugin. Qui elimini le tabelle dal database, rimuovi le options dalla tabella wp_options e ripulisci tutti i dati creati dal plugin. Implementa sempre questi hook, perché un plugin che lascia dati nel database dopo la disinstallazione è una cattiva pratica che occupa risorse inutilmente e inquina il database.

Sicurezza e best practice

La sicurezza è fondamentale nello sviluppo di plugin, perché un plugin vulnerabile può compromettere l'intera installazione di WordPress e tutti i siti sullo stesso server. Convalida e sanitizza sempre tutti gli input degli utenti con sanitize_text_field(), absint(), esc_url() e altre funzioni di sanitizzazione di WordPress. Usa prepared statement con $wpdb->prepare() per tutte le query al database per prevenire attacchi SQL injection.

• Verifica del nonce - wp_nonce_field() e wp_verify_nonce() per la protezione CSRF
• Controllo delle capability - current_user_can() prima di ogni azione privilegiata
• Escaping dell'output - esc_html(), esc_attr(), esc_url() per tutti i dati dinamici nell'HTML
• Prepared statement - $wpdb->prepare() per tutte le query con dati utente
• Validazione degli upload - controlla tipo MIME, dimensione del file ed estensione
• Protezione dall'accesso diretto - defined('ABSPATH') || exit; all'inizio di ogni file PHP

Segui i WordPress Coding Standards per un codice coerente e leggibile. Usa il sistema di internazionalizzazione di WordPress con le funzioni __() e _e() per tutte le stringhe visibili all'utente, così che il tuo plugin possa essere tradotto in altre lingue. Testa il plugin con WP_DEBUG abilitato per intercettare tutti gli errori e i warning prima della pubblicazione. Valuta la scrittura di test PHPUnit per la logica critica del plugin, perché i test automatizzati prevengono le regressioni durante gli aggiornamenti.