In questo articolo vedremo come è strutturato un plugin di WordPress al suo interno. I plugin di WordPress seguono una struttura predefinita solo per alcune parti, mentre per altre la scelta dipende dall’autore del plugin.
Prima di iniziare è bene ricordare che un plugin per essere attivato con successo non deve contenere errori di sintassi PHP. In caso contrario il plugin non verrà attivato e WordPress mostrerà un messaggio contenente i dettagli dell’errore. Inoltre quando si lavora con i plugin è sempre consigliabile abilitare la modalità di debug di WordPress nel file wp-config.php impostando la costante WP_DEBUG su true.
Struttura dei file e delle directory
La pratica comunemente seguita e raccomandata è quella di dare al file principale del plugin lo stesso nome della directory in cui sono contenuti i file del plugin. Quindi se la directory viene chiamata myplugin, il file principale del plugin verrà nominato myplugin.php. Tuttavia, come vedremo in seguito, questo non basta ancora affinché WordPress includa un plugin nell’elenco della sezione Plugin nel backend.
I plugin vanno inseriti nella directory wp-content/plugins. WordPress analizza il contenuto di questa directory ad ogni sua inizializzazione. Quindi il percorso del nostro ipotetico plugin sarà wp-content/plugins/myplugin/myplugin.php (come vedremo WordPress dispone di diverse funzioni e costanti per far riferimento sia all’URL assoluto che al percorso dei plugin ).
Il file principale del plugin può di fatto contenere l’intero codice del plugin. Tuttavia questa soluzione si applica solo nel caso di plugin molto semplici. Nel caso invece di plugin più complessi, il file principale del plugin servirà semplicemente a caricare il codice del plugin che risiederà in file esterni che si troveranno sempre all’interno della directory principale del plugin stesso.
Un plugin di solito non contiene solo file PHP, ma anche file CSS, JavaScript ed immagini. Queste risorse possono essere utilizzate sia nel frontend che nel backend del sito, come ad esempio nel pannello di controllo del plugin (per le sue impostazioni). La struttura delle directory aggiuntive e dei nomi dei file ausiliari di fatto non segue alcuno schema predefinito, anche se la community di WordPress incoraggia gli autori di plugin ad usare una strutturazione coerente.
Il file principale del plugin
Di fatto l’unico punto saldo nella struttura di un plugin è il suo file principale. WordPress riconosce un plugin come valido se all’inizio di questo file è contenuto un blocco di commenti che ha la seguente struttura:
/*
Plugin Name: My Plugin
Version: 1.0
Description: Descrizione del plugin
Author: Nome Cognome
Author URI: http://sito.com
*/Questi sono i metadati del plugin che verranno usati da WordPress per identificarlo nel backend. La prima riga dichiara il nome del plugin, la seconda il numero di versione, la terza la descrizione, la quarta mostra l’autore del plugin e la quinta l’URL del sito dell’autore del plugin. Quando il plugin viene attivato le informazioni contenute in questi metadati vengono salvate nel database aggiungendole alla stringa contenuta nel campo active_plugins della tabella wp_options (si tratta di una stringa serializzata).
Dopo questo blocco iniziale l’autore del plugin può inserire il suo codice che, come abbiamo anticipato, può essere interamente contenuto nel file principale o basato su file esterni richiamati tramite le funzioni PHP require() o require_once(). Una volta attivato, il codice del plugin è disponibile globalmente nel flusso di WordPress. Quindi se il plugin definisce una funzione chiamata my_func() questa sarà disponibile nella nostra installazione di WordPress, ovviamente nel contesto che le è proprio (frontend o backend) secondo le scelte di design dell’autore del plugin. Quando il plugin viene disattivato o non è presente, la nostra funzione my_func() non sarà più disponibile.
Percorsi ed URL
C’è una differenza sostanziale tra percorsi ed URL quando si parla di plugin e più in generale di tutto ciò che ha a che fare con WordPress. Un "percorso" (path) fa riferimento al file system del server che ospita WordPress, mentre un "URL" fa riferimento al protocollo HTTP e al dominio su cui risiedono i file.
Quindi /home/nomeutente/sito.com/public_html/wp-content/plugins/my_plugin è un percorso, mentre http://sito.com/wp-content/plugins/my_plugin/ è un URL.
I percorsi vengono usati per includere i file PHP, mentre gli URL per includere i file CSS, JavaScript e le immagini. WordPress gestisce i percorsi tramite la funzione plugin_dir_path() che restituisce il percorso alla directory del plugin compreso lo slash finale. Quindi nel file principale del plugin possiamo scrivere:
define( ‘MY_PLUGIN_PATH’, plugin_dir_path( __FILE__ ) );
// /home/nomeutente/sito.com/public_html/wp-content/plugins/my_plugin/e quindi includere i file PHP in questo modo:
require_once( MY_PLUGIN_PATH . ‘framework/MyClass.php’ );Al contrario la funzione plugin_dir_url() restituisce l’URL assoluto alla directory principale del plugin compreso lo slash finale. Quindi nel file principale del plugin possiamo scrivere:
define( ‘MY_PLUGIN_URL’, plugin_dir_url( __FILE__ ) );
// http://sito.com/wp-content/plugins/my_plugin/e quindi usare l’URL in questo modo:
wp_register_script( ‘my’, MY_PLUGIN_URL . ‘js/my.js’, array( ‘jquery’ ), ‘1.0’, true );Da segnalare anche la funzione plugins_url() che ha uno scopo identico anche se con parametri diversi.
Tutte queste funzioni si basano sul file o sulla directory passata come parametro per restituire il percorso o l'URL corretto. In PHP __FILE__ fa riferimento al file corrente in cui viene invocato. Quindi usarlo in my_plugin/my_plugin.php e in my_plugin/framework/MyClass.php restituirà due valori distinti poiché i file non si trovano nella stessa directory.
Ora che abbiamo chiara la struttura di un plugin dal punto di vista dell’organizzazione del codice, possiamo entrare nel merito dello sviluppo del codice di un plugin di WordPress.