Struttura di un plugin WordPress
Un plugin WordPress è fondamentalmente una directory contenente file PHP che estendono le funzionalità del CMS. La struttura minima richiede un file principale con un’intestazione specifica riconosciuta da WordPress. Puoi posizionare la directory del plugin in wp-content/plugins/ o in wp-content/mu-plugins/ per i must-use plugin.
La struttura consigliata per un plugin ben organizzato include:
- plugin-name.php (file principale con header comment)
- README.txt (informazioni per il repository WordPress.org)
- admin/ (file per il backend)
- includes/ (classi e funzioni condivise)
- public/ (file per il front-end)
- languages/ (file di traduzione .po/.mo)
- assets/ (CSS, JS, immagini)
Il file principale e l’header comment
Il file principale del plugin deve iniziare con un header comment che WordPress utilizza per identificare e visualizzare il plugin nella schermata di amministrazione. Ecco la struttura obbligatoria:
L’header include: Plugin Name, Plugin URI, Description, Version, Requires at least, Requires PHP, Author, Author URI, License e License URI. Campi aggiuntivi come Text Domain e Domain Path sono necessari per l’internazionalizzazione.
Dopo l’header, usa un controllore di accesso diretto per impedire l’esecuzione del file se chiamato direttamente via URL: if (!defined('ABSPATH')) exit;. Questo è uno standard di sicurezza fondamentale.
Attivazione, disattivazione e disinstallazione
WordPress fornisce hook specifici per gestire il ciclo di vita del plugin. register_activation_hook() esegue codice all’attivazione: creazione di tabelle personalizzate, impostazione di opzioni predefinite, controllo dei requisiti di sistema.
register_deactivation_hook() esegue codice alla disattivazione: pulizia di cache temporanee, disattivazione di cron job, ma non deve mai eliminare dati utente. Questo è importante: l’utente potrebbe riattivare il plugin in futuro e ritrovare i propri dati intatti.
Per la disinstallazione, il metodo migliore è usare un file uninstall.php nella root del plugin. Viene eseguito solo quando l’utente elimina il plugin, non alla semplice disattivazione. Qui puoi rimuovere definitivamente tutte le opzioni, tabelle e dati creati dal plugin.
Aggiungere una pagina di impostazioni
La maggior parte dei plugin offre una pagina di impostazioni nel backend. Puoi aggiungerla usando le WordPress Settings API, che gestiscono automaticamente validazione e salvataggio dei dati. Le funzioni principali sono:
- add_options_page() o add_menu_page() per registrare la pagina
- register_setting() per registrare le opzioni
- add_settings_section() e add_settings_field() per strutturare il form
- do_settings_sections() e settings_fields() per renderizzare il form
Le Settings API seguono il principio di separazione tra presentazione e logica. Definisci i campi in una funzione e renderizzali in un template. Questo rende il codice manutenibile e facile da estendere.
Creare custom post type e tassonomie
I custom post type (CPT) permettono di aggiungere tipi di contenuto personalizzati oltre a post e pagine. Si registrano con register_post_type(), specificando label, supporti (thumbnail, editor, excerpt), rewrite rules e capacità. Per portfolio, testimonianze, eventi, prodotti (se non usi WooCommerce), i CPT sono la soluzione ideale.
Le tassonomie personalizzate (register_taxonomy()) aggiungono sistemi di categorizzazione specifici per i tuoi CPT. Se crei un CPT “Libri”, puoi registrare una tassonomia “Genere” per classificarli. Le tassonomie supportano gerarchia (come le categorie) o piatta (come i tag).
Dopo aver registrato CPT e tassonomie, flusha le rewrite rule con flush_rewrite_rules() durante l’attivazione del plugin, mai a ogni caricamento della pagina.
Shortcode e widget
Gli shortcode permettono agli utenti di inserire funzionalità complesse nei contenuti con una semplice sintassi [mioshortcode]. Si registrano con add_shortcode() e accettano attributi e contenuto racchiuso. Un esempio classico è uno shortcode che mostra un pulsante personalizzato: [pulsante colore=”rosso” url=”https://esempio.com”]Clicca qui[/pulsante].
I widget sono blocchi riutilizzabili posizionabili nelle sidebar. La vecchia API (WP_Widget) è ancora supportata, ma dal 2024 il futuro sono i Block Widget basati su Gutenberg. Per nuovi plugin, sviluppa widget come blocchi Gutenberg: sono più flessibili e compatibili con il Full Site Editing.
Esporre API REST endpoints
WordPress REST API è il modo moderno per interagire con i dati del sito via HTTP. Puoi registrare endpoint personalizzati usando register_rest_route(). Ogni endpoint specifica namespace, route, metodi (GET, POST, PUT, DELETE) e callback di autorizzazione.
Esempio pratico: un endpoint /mioplugin/v1/dati che restituisce dati in formato JSON a chiamate AJAX dal front-end. La REST API gestisce automaticamente serializzazione, validazione e permessi. Usa sempre permission_callback per verificare che l’utente abbia i diritti necessari.
Per la sicurezza degli endpoint, implementa nonce verification per le richieste provenienti dal front-end e verifica le capability per le richieste amministrative.
Best practice di sicurezza
Scrivere plugin sicuri è fondamentale. WordPress fornisce numerose API per proteggere il codice:
- Nonce: usa wp_create_nonce() e wp_verify_nonce() per proteggere form e URL da CSRF
- Sanitizzazione: usa sanitize_text_field(), sanitize_email(), sanitize_html_class() per pulire i dati in ingresso
- Validazione: verifica che i dati siano del tipo e formato attesi prima di processarli
- Capability check: usa current_user_can() per verificare i permessi utente prima di eseguire operazioni sensibili
- Preparazione query: usa $wpdb->prepare() per tutte le query SQL che includono variabili
- Escaping output: usa esc_html(), esc_attr(), esc_url() per proteggere l’output verso il browser
Non fidarti mai dell’input utente. Anche gli amministratori possono essere ingannati da attacchi XSS. Ogni dato che arriva da $_GET, $_POST, $_REQUEST o dal database deve essere trattato come potenzialmente pericoloso fino a prova contraria.
Internazionalizzazione
Per rendere il tuo plugin traducibile, usa le funzioni di WordPress: __() e _e() per stringhe semplici, _n() per plurali, _x() e _ex() per stringhe con contesto. Il text domain deve corrispondere al nome della directory del plugin, come dichiarato nell’header comment.
Genera il file .pot con strumenti come Poedit o WP-CLI, poi traduci in .po e compila in .mo. Per caricare le traduzioni, usa load_plugin_textdomain() all’inizio del plugin. Se distribuisci su WordPress.org, le traduzioni vengono caricate automaticamente dal translate.wordpress.org.
Distribuzione su WordPress.org
Pubblicare un plugin sul repository ufficiale di WordPress.org lo rende disponibile a milioni di utenti. Il processo richiede:
- Sviluppare il plugin seguendo tutte le best practice WordPress
- Creare un README.txt ben formattato con descrizione, installazione, FAQ e changelog
- Eliminare codice offensivo, backlink nascosti, eval, base64_decode e qualsiasi altra pratica scorretta
- Sottoporre il plugin per la revisione tramite la pagina Plugin Developer di WordPress.org
- Il team di revisione controlla il codice per sicurezza, standard e qualità. Il processo può richiedere da pochi giorni a settimane.
Una volta approvato, il plugin avrà una pagina su WordPress.org, statistiche di download, valutazioni degli utenti e aggiornamenti automatici per gli installati. Mantieni il plugin aggiornato, rispondi ai ticket di supporto e aggiorna la compatibilità con le ultime versioni di WordPress.
Conclusione
Creare un plugin WordPress da zero è più accessibile di quanto sembri. Seguendo la struttura standard, utilizzando le API ufficiali e applicando le best practice di sicurezza, puoi sviluppare plugin robusti e professionali. Inizia con un plugin semplice (uno shortcode, una pagina di impostazioni) e gradualmente aggiungi complessità. La documentazione ufficiale WordPress Developer Resources è il tuo miglior alleato: è completa, aggiornata e ricca di esempi pratici.