WordPress.org

Codex

Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

it:Scrivi un Plugin

Introduzione

I Plugins di WordPress permettono facili modifiche, personalizzazioni, e miglioramento del sito WordPress. Invece di modificare i componenti fondamentali della programmazione di WordPress, puoi aggiungere funzionalità con i Plugins di WordPress. Questa è la definizione base:

Plugin WordPress: Un Plugin WordPress è un programma, una o più serie di funzioni, scritte in linguaggio di programmazione PHP, che aggiungono specifiche set di funzionalità o servizi al sito WordPress, che può essere perfettamente integrato con il sito utilizzando i punti di accesso e le modalità previste dal Plugin Application Program Interface (API) di WordPress.

Desideri che WordPress abbia funzionalità nuove o modificate? La prima cosa da fare è ricercare nei vari repository dei Plugin di WordPress e nei codici sorgente, se qualcuno ha già creato un Plugin WordPress che rispecchia le tue esigenze. Se non è così, questo articolo ti guiderà attraverso il processo di creazione del tuo Plugin di WordPress.

Questo articolo presuppone che hai familiarità con le funzionalità base di WordPress, e il linguaggio di programmazione PHP.

Risorse

  • Per comprendere come un Plugin di WordPress funziona e come si installa nel tuo sito WordPress, vedi I Plugins di WordPress.
  • C'è una lista esaustiva di articoli e risorse per gli sviluppatori di Plugins, incluso articoli esterni su come scrivere Plugins di WordPress, e speciali argomenti, vedi Risorse per Plugin.
  • Per imparare le basi su come i Plugins WordPress sono scritti, visualizza il codice sorgente dei Plugins che adottano le best-practise, come ad esempio Hello Dolly distribuiti da WordPress.
  • Una volta che hai scritto il tuo Plugin di WordPress, leggi Plugin Submission and Promotion per imparare a distribuirli e condividerli con gli altri.

Creare un Plugin

Questa sezione dell'articolo affronta gli steps necessari da seguire e le questioni da considerare quando si crea un Plugin WordPress ben strutturato.

Nomi, Files e Posizioni

Nome del Plugin

Il primo processo per la creazione di un Plugin WordPress è di pensare a che cosa si vuol far fare al Plugin, quindi creare un nome (necessariamente unico) per il tuo Plugin. Controlla la sezione I Plugins di WordPress e gli altri repository a cui si riferisce, per verificare che il nome scelto sia unico; dovresti anche verificarlo effettuando ricerche con Google. La maggior parte degli sviluppatori di Plugins scelgono di utilizzare nomi che descrivono le funzionalità del Plugin; per esempio, un Plugin inerente al meteo potrebbe avere la parola "meteo" nel nome. Il nome può essere composto da più parole.

I Files del Plugin

Il prossimo step è di creare un file PHP con un nome derivato dal nome del Plugin scelto. Per esempio, se il tuo Plugin verrà chiamato "Funzionalità Favolosa", dovresti chiamare il tuo file PHP "funzionalita-favolosa.php". Di nuovo, cerca di scegliere un nome unico. Le persone che installeranno il tuo Plugin scaricheranno questo file PHP dentro la directory di installazione dei Plugins di WordPress (di norma "wp-content/plugins/"), quindi due Plugins che stanno usando non possono avere lo stesso nome del file PHP.

Un'altra opzione è di dividere il tuo Plugin in files multipli. Il tuo Plugin di WordPress Plugin deve avere almeno un file PHP; può contenere anche files JavaScript, files CSS, files di immagine, files della lingua, ecc. Se ci sono più files, scegli un nome unico per la cartella e un nome a tua scelta per (di solito lo stesso) per il file PHP principale del tuo Plugin, come ad esempio funzionalita-favolosa e funzionalita-favolosa.php, rispettivamente, posiziona tutti i files del tuo Plugin in quella directory, e comunica agli utenti che vorranno usare il tuo Plugin di caricare l'intera cartella dentro wp-content/plugins/. Nota che l'installazione di WordPress può essere configurata per spostare la cartella wp-content/plugins/', quindi utilizza le funzioni plugin_dir_path() e plugins_url() per i percorsi assoluti e gli URLs. Per maggiori dettagli vedi Determining Plugin and Content Directories.

Nel resto di questo articolo, "il file Plugin PHP" si riferisce al file principale PHP del Plugin, sia che si trovi in wp-content/plugins/ o in sua sotto-cartella.

Nota di Sicurezza: Considera di bloccare l'accesso diretto ai tuoi file PHP del tuo Plugin aggiungendo la riga seguente all'inizio di ognuno di essi, o di essere sicuri di non permettere l'esecuzione di codice PHP sensibile prima di chiamare ogni funzione di WordPress.

defined( 'ABSPATH' ) or die( 'No script kiddies please!' );

File Leggimi

Se vuoi caricare il tuo Plugin su https://wordpress.org/plugins/, è necessario che crei un file readme.txt in formato standard e lo includi con il tuo Plugin. Vedi https://wordpress.org/plugins/about/readme.txt per una descrizione del formato da utilizzare o usa il generatore 'readme.txt' di plugin automatico.

Nota che il repository dei Plugin di WordPress rileva le versioni di "Requires" e "Tested up to" dal file readme.txt scritto con i tag standard.

Pagina Home

E' molto utile creare una pagina che funga come pagina principale per il tuo Plugin. Questa pagina dovrebbe descrivere come installare il Plugin, che cosa fa, con quale versione di WordPress è compatibile, che cosa è cambiato da una versione all'altra del tuo Plugin, e come utilizzare il Plugin.

File Headers

E' arrivato il momento di inserire alcune informazioni dentro il tuo file PHP principale del Plugin.

Informazioni Plugin Standard

Leggi questo nel plugin developer handbook.

Licenza

Leggi questo nel plugin developer handbook.

Programmare il tuo Plugin

Ora è giunto il momento di far fare al tuo Plugin qualcosa di utile. Questa sezione contiene alcune idee generiche sullo sviluppo dei Plugin, e descrive come far fare al tuo Plugin alcune cose che è necessario che faccia.

WordPress Plugin Hooks

Molti Plugin di Wordpress svolgono il loro compito collegandosi ad uno o più "hooks" definiti in WordPress. Quando WordPress gira controlla per vedere se qualche Plugin ha registrato delle funzioni da eseguire in quel momento, ed in tal caso la funzione viene eseguita. Queste funzioni modificano il normale funzionamento di WordPress.

Per esempio, prima che WordPress aggiunga il titolo di un post all'output da inviare al browser, controlla se qualche Plugin ha registrato una funzione che "filtra" (filter) lo hook chiamato "the_title". Se si, il testo del titolo viene passato a tutte le funzioni registrate e ciò che viene restituito dalle funzioni viene stampato. Perciò se il tuo Plugin ha bisogno di aggiungere qualche informazione al titolo di un post, deve registrare la filter function per "the_title".

Un altro esempio è il "action" hook chiamato "wp_footer". Subito prima della fine della pagina HTML che WordPRess sta generando, viene controllato se qualche Plugin ha registrato la funzione per lo hook "wp_footer" ed nel caso esegue quello.

Per imparare a registrare funzioni per gli hooks di tipo action e filter e quali hooks sono disponibili in WordPress, puoi consultare la Plugin API. Se trovi una posizione nel codici di WordPress in cui vorresti avere uno hook, ma che al momento non c'è, puoi suggerire di aggiungerlo, (e di solito i suggerimenti vengono accettati); vedi Reporting Bugs per capire come.

Template Tags

Un'altro punto chiave dei Plugin di WorPress per aggiungere funzionalità è quella di creare Template Tags personalizzati. E poi chi desidera utilizzare il tuo Plugin può aggiungere questi "tags" al proprio tema, nella sidebar, nel contenuto principale o in qualsiasi altra posizione. Per esempio, un Plugin che aggiunge tags geografici ai posts, può definire una funzione di template tag chiamata geotag_list_states() per la sidebar, che elenca tutti i post taggati, con links verso le pagine degli stati che il Plugin abilita.

Per definire tag di template personalizzati, basta scrivere una funzione PHP e documentarla per gli utenti del Plugin nella home page del Plugin e/o nel file PHP principale del Plugin. Quando si documenta una funzione è opportuno fornire un esempio di che cosa è richiesto esattamente per aggiungere al tema la funzione comprese le direttive <?php e ?>.

Salvare i dati del Plugin nel Database

Molti Plugin di WordPRess hanno necessità di ottenere qualche input dal proprietario del sito o dagli utenti del blog e di mantenere questi dati permaneti, per utilizzarli nelle proprie filter functions, action functions e template functions. Queste informazione devono essere salvate nel database di WordPRess per renderle persistenti tra una sessione e al successiva. Ci sono quattro (4) metodi per salvare i dati dei Plugin nel database:

  1. Usare il meccanismo "option" di WordPress (descritto in seguito). Questo sistema è adeguato per salvare dati relativamente piccoli e relativamente statici, chiamati pezzi di dati -- sono i tipi di dati che solitamente il proprietario del sito inserisce la prima volta che configura il Plugin ed in seguito modifica raramente.
  2. Post Meta (chiamati anche Custom Fields). Sono adatti per dati associati a singoli posts, pagine, o attachments. Vedi post_meta Function Examples, add_post_meta(), e le funzioni correlate.
  3. Custom Taxonomy. Per classificare i posts o altri oggetti come utenti e commenti, oppure per aggiungere liste nome/valore editabili dagli utenti si può pensare di usare una Custom Taxonomy, in particolar modo quando si desidera accedere a tutti a tutti i posts o oggetti associati con i termini della tassonomia. Vedi Custom Taxonomies.
  4. Creare una nuova tabella di database personalizzata. Questo metodo è adeguato per i dati non associati a singoli posts, pagine, allegati o commenti -- si usa per i tipi di dati che crescono con il tempo e che non hanno nomi individuali. Vedi Creating Tables with Plugins per informazioni su come fare.

Il funzionamento delle Options di WordPress

Vedi Creating Options Pages per informazioni su come creare pagine che salvano automaticamente le options per te.

WordPress dispone di meccanismi per salvare, aggiornare e recuperare individuali pezzi di dati chiamati "options" nel database di WordPRess. I dati delle options possono essere stringhe, arrays o oggetti PHP (che vengono "serializzati" per essere convertiti in stringa prima di essere salvati e "deserializzati" quando vengono recuperati). I nomi delle Options sono stringhe e devono essere univoci in modo da non andare in conflitto con quelli definiti da WordPress o o da altri Plugin.

Solitamente è considerata una buona pratica quella di minimizzare il numero di opzioni utilizzate dal proprio Plugin. Per esempio invece di memorizzare 10 opzioni con nomi diversi si valuti di serializzare un array di 10 elementi con un nome singolo.

Queste sono le principali funzioni che il tuo Plugin può utilizzare per accedere alle opzioni di WordPress.

add_option($name, $value, $deprecated, $autoload);
Crea una nuova opzione e non fa niente se l'opzione esiste già.
$name
Obbligatorio (string). Il nome della opzione da aggiungere.
$value
Opzionale (mixed), di default è una stringa vuota. Il valore della option da memorizzare.
$deprecated
Opzionale (string), non più utilizzata da WordPress. Devi passare una stringa vuota o null a questo argomento se vuoi usare il parametro successivo che è $autoload.
$autoload
Opzionale, di default 'yes' (enum: 'yes' o 'no'). Se impostato a 'yes' questa option viene caricata automaticamente dalla funzione wp_load_alloptions.
get_option($option);
Recupera dal database il valore di una option.
$option
Obbligatorio (string). Il nome della option che deve essere restituito. Puoi trovare la lista delle options che vengono installate con WordPress alle Option Reference.
update_option($option_name, $newvalue);
Aggiorna o crea il valore di una option nel database. (nota che se usi questa funzione non hai necessità di chiamare add_option se non ti serve usare i parametri $deprecated o $autoload).
$option_name
Obbligatorio (string). Il nome della option da aggiornare.
$newvalue
Obbligatorio. (string|array|object) Il nuovo valore per la option.

Pannelli di Amministrazione

Se il tuo Plugin ah alcune options memorizzate nel database di WordPress (vedi sopra), probabilmente desideri avere un pannello di amministrazione che permette agli utenti del plugin di vedere e modificarne i valori. I metodi per fare questo sono descritti in Adding Administration Menus.

Tradurre in altre lingue il tuo Plugin

Dopo che hai terminato di scrivere il tuo Plugin e se intendi distribuirlo, puoi prendere in considerazione la internazionalizzazione. La Internazionalizzazione è il procedimento di configurazione del software che gli permette di essere localizzato; la localizzazione è il procedimento di traduzione dei testi presenti nel software nelle diverse lingue. WordPRess viene usato in tutto il mondo, e perciò ha la internazionalizzazione e la localizzazione compresa la localizzazione dei Plugins, insita nella propria struttura.

È da notare che i files delle lingue per i Plugins NON VENGONO caricati automaticamente. Per essere sicuri che i files delle lingue vengano caricati si deve aggiungere questo comando:

	load_plugin_textdomain('your-unique-name', false, basename( dirname( __FILE__ ) ) . '/languages' );

E poi per caricare una stringa basta usare __('String name','your-unique-name'); per ottenere la traduzione oppure _e('String name','your-unique-name'); scrivere il valore direttamente in output con echo. Le traduzioni dovranno essere memorizzate nella cartella /languages del tuo Plugin.

Si raccomanda caldamente di internazionalizzare i propri Plugin, in modo da permettere agli utenti di nazioni diverse di localizzarli. I riferimenti completi sulla internazionalizzazione comprese le sezioni che descrivono come internazionalizzare i Plugin si possono trovare su I18n for WordPress Developers.

(NdT e si consiglia di scrivere i Plugin sempre in inglese ed eventualmente fornire la traduzione per la propria lingua).

Aggiornamento del tuo Plugin

Questa sezione descrive i passaggi necessari per aggiornare il tuo Plugin quando lo ospiti su https://wordpress.org/plugins/ inclusi i dettagli su come usare Subversion (SVN) with wordpress.org.

Supponendo che tu abbia già pubblicato il tuo Plugin nel WordPress Plugin Repository, probabilmente nel corso del tempo probabilmnnte troverai il bisogno, e speriamo anche il tempo, di aggiungere funzionalità al tuo Plugin oppure di risolvere qualche bug. Lavora a queste modifiche e pubblica i cambiamenti al trunk di sviluppo tutte le volte che vuoi. Le modifiche saranno pubblicamente visibili, ma solo ma solo per le persone di formazione tecnica che accedono al tuo Plugin via SVN. Quello che scaricano le altre persone dal sito o dal proprio pannello di amministrazione WordPress non cambia.

Quando sei pronto per pubblicare la nuova versione del Plugin:

  • Assicurati che quello che è stato pubblicato e la nuova versione funzioni bene. Fai attenzione alle versioni di WordPress che il tuo Plugin supporta e prova a testarlo con tutte. Non testare solo le nuove funzionalità, ma assicurati anche di non aver rotto per errore alcune delle vecchie funzionalità.
  • Cambia il numero di versione nei commenti header del file PHP principale con il nuovo numero di versione (nella cartella trunk).
  • Cambia il numero di versione nel campo 'Stable tag' del file readme.txt (nella cartella trunk).
  • aggiungi un nuovo sub-version nella sezione 'changelog' del file readme.txt descrivendo brevemente i cambiamenti rispetto alla versione precedente. Questo verrà elencato nel tab 'Changelog' della pagina del Plugin.
  • Consegna (commit) le modifiche.
  • Crea un nuovo tag SVN con una copia del trunk, seguendo questa guida.

Concedi al sistema alcuni minuti per eseguire l'elaborazione, e poi controlla la pagina dei Plugin di wordpress.org e una installazione di WordPress con il tuo Plugin per vedere se tutto si aggiorna correttamente e se l'installazione di WordPress evidenzia la presenza di un aggiornamento (il controllo di aggiornamento ha una memoria temporanea aggiornata di notte, e quindi questo potrebbe richiedere abbastanza tempo -- prova a visitare la pagina degli 'aggiornamenti disponibili' nella tua installazione di WordPRess).

Soluzione dei problemi:

  • La pagina dei Plugin in wordpress.org fa vedere la versione vecchia. Hai aggiornato il 'stable tag' del tunk folder? Solo creare il tag ed aggiornare il file readme.txt nella cartella non è sufficiente!
  • La pagina del Plugin offre il file zip con la nuova versione, ma nel pulsante c'è ancora indicata la versione vecchia e la tua installazione WorPress non ti notifica l'aggiornamento. Ti sei ricordato di aggiornare il commento 'Version' nel file PHP principale?
  • Per altri problemi consulta l'ottimo scritto di Otto sui problemi comuni: The Plugins directory and readme.txt files

Suggerimenti per lo sviluppo di Plugins

L'ultima sezione di questo testo contiene vari suggerimenti in merito allo sviluppo dei Plugin.

  • Il codice dei Plugin WordPress dovrebbe seguire le WordPress Coding Standards. E considera anche se adottare anche gli Inline Documentation Standards.
  • Tutti i nomi di funzione del tuo Plugin devono essere unici e diversi dai nomi delle funzioni di WordPress, degli altri Plugin e dei temi. Per evitare conflitti può essere utile usare un prefisso univoco in tutte le funzioni del Plugin. Una soluzione ancora migliore è quella di definire tutte le funzioni all'interno di una classe (che comunque deve essere essa stessa unica).
  • Non forzare il prefisso delle tabelle di database nel codice del Plugin. Assicurati invece di usare sempre la variabile $wpdb->prefix.
  • Le letture dal database sono veloci, le scritture invece sono lente. I database sono di solito velocissimi al leggere i dati che contengono. Scrivere modifiche nel database invece è un procedimento più complicato che richiede maggiori capacità di computazione. Di conseguenza cerca di minimizzare il numero di scritture che fai nel database. Se puoi, prima prepara tutto quello che devi scrivere e poi fallo in un colpo solo.
  • Se possibile usa le API di WordPress invece di usare direttamente comandi SQL. Per esempio usa get_posts() o new WP_Query() invece di SELECT * FROM {$wpdb->prefix}_posts.
  • Se possibile usa le tabelle di database esistenti invece di creare nuove tabelle personalizzate. Nella maggior parte dei casi si può realizzare tutto con tipi di post personalizzati e metadata, tassonomie personalizzate e/o una delle altre tabelle standard, questo consente di utilizzare moltissime UI e altre funzionalità già previste senza necessità di riscriverle. Pensa molto attentamente priam di aggiungere perché aggiunge complessità al tuo Plugin e di solito gli utenti e coloro che progettano siti tendono a preferire le soluzioni semplici.
  • Seleziona (SELECT) solo quello che ti serve. Anche se il database è velocissimo a recuperare dati, dovresti comunque cercare di limitare i dati da leggere a quelli che effettivamente ti servono. Ad esempio si ti serve solamente contare il numero di righe di una tabelle non chiedere SELECT * FROM, perché questo legge anche tutti i dati presenti nelle righe e questo spreca memoria. Allo stesso modo, se ti servono solo il post_id ed il post_author nel tuo Plugin fai il SELECT solamente di questi specifici campi, per minimizzare le operazioni di lettura. Ricordati che altri centinaia di processi potrebbero richiedere dati nello stesso istante. Imparare a minimizzare le richieste al database fa in modo che il tuo Plugin non venga accusato di sprecare risorse.
  • Elimina gli errori PHP dal tuo Plugin. Aggiungi define('WP_DEBUG', true); al tuo file wp-config.php, prova tutte le funzionalità del plugin, e controlla che non ci siano errori o warnings. Risolvi i bugs e rimani in modalità debug finché non li avrai eliminati tutti.
  • Cerca di evitare di scrivere direttamente le direttive di <script> e <style>. Invece usa le le funzioni raccomandate wp_enqueue_style() e wp_enqueue_script() che aiutano ed eliminare inclusioni duplicate di script e fogli di stile ed introducono anche il supporto delle dipendenze. Vedi i posts di queste persone per maggiori informazioni: Ozh Richard, Artem Russakovskii, e Vladimir Prelovac.

Risorse Esterne