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

Now, it's time to make your Plugin actually do something. This section contains some general ideas about Plugin development, and describes how to accomplish several tasks your Plugin will need to do.

WordPress Plugin Hooks

Many WordPress Plugins accomplish their goals by connecting to one or more WordPress Plugin "hooks". The way Plugin hooks work is that at various times while WordPress is running, WordPress checks to see if any Plugins have registered functions to run at that time, and if so, the functions are run. These functions modify the default behavior of WordPress.

For instance, before WordPress adds the title of a post to browser output, it first checks to see if any Plugin has registered a function for the "filter" hook called "the_title". If so, the title text is passed in turn through each registered function, and the final result is what is printed. So, if your Plugin needs to add some information to the printed title, it can register a "the_title" filter function.

Another example is the "action" hook called "wp_footer". Just before the end of the HTML page WordPress is generating, it checks to see whether any Plugins have registered functions for the "wp_footer" action hook, and runs them in turn.

You can learn more about how to register functions for both filter and action hooks, and what Plugin hooks are available in WordPress, in the Plugin API. If you find a spot in the WordPress code where you'd like to have an action or filter, but WordPress doesn't have one, you can also suggest new hooks (suggestions will generally be taken); see Reporting Bugs to find out how.

Template Tags

Another way for a WordPress Plugin to add functionality to WordPress is by creating custom Template Tags. Someone who wants to use your Plugin can add these "tags" to their theme, in the sidebar, post content section, or wherever it is appropriate. For instance, a Plugin that adds geographical tags to posts might define a template tag function called geotag_list_states() for the sidebar, which lists all the states posts are tagged with, with links to the state-based archive pages the Plugin enables.

To define a custom template tag, simply write a PHP function and document it for Plugin users on your Plugin's home page and/or in the Plugin's main PHP file. It's a good idea when documenting the function to give an example of exactly what needs to be added to the theme file to use the function, including the <?php and ?>.

Saving Plugin Data to the Database

Most WordPress Plugins will need to get some input from the site owner or blog users and save it between sessions, for use in its filter functions, action functions, and template functions. This information has to be saved in the WordPress database, in order to be persistent between sessions. There are four (4) methods for saving Plugin data in the database:

  1. Use the WordPress "option" mechanism (described below). This method is appropriate for storing relatively small amounts of relatively static, named pieces of data -- the type of data you'd expect the site owner to enter when first setting up the Plugin, and rarely change thereafter.
  2. Post Meta (a.k.a. Custom Fields). Appropriate for data associated with individual posts, pages, or attachments. See post_meta Function Examples, add_post_meta(), and related functions.
  3. Custom Taxonomy. For classifying posts or other objects like users and comments and/or for a user-editable name/value list of data consider using a Custom Taxonomy, especially when you want to access all posts/objects associated with a given taxonomy term. See Custom Taxonomies.
  4. Create a new, custom database table. This method is appropriate for data not associated with individual posts, pages, attachments, or comments -- the type of data that will grow as time goes on, and that doesn't have individual names. See Creating Tables with Plugins for information on how to do this.

WordPress Options Mechanism

See Creating Options Pages for info on how to create a page that will automatically save your options for you.

WordPress has a mechanism for saving, updating, and retrieving individual, named pieces of data ("options") in the WordPress database. Option values can be strings, arrays, or PHP objects (they will be "serialized", or converted to a string, before storage, and unserialized when retrieved). Option names are strings, and they must be unique, so that they do not conflict with either WordPress or other Plugins.

It's also generally considered a good idea to minimize the number of options you use for your plugin. For example, instead of storing 10 different named options consider storing a serialized array of 10 elements as a single named option.

Here are the main functions your Plugin can use to access WordPress options.

add_option($name, $value, $deprecated, $autoload);
Creates a new option; does nothing if option already exists.
$name
Required (string). Name of the option to be added.
$value
Optional (mixed), defaults to empty string. The option value to be stored.
$deprecated
Optional (string), no longer used by WordPress, You may pass an empty string or null to this argument if you wish to use the following $autoload parameter.
$autoload
Optional, defaults to 'yes' (enum: 'yes' or 'no'). If set to 'yes' the setting is automatically retrieved by the wp_load_alloptions function.
get_option($option);
Retrieves an option value from the database.
$option
Required (string). Name of the option whose value you want returned. You can find a list of the default options that are installed with WordPress at the Option Reference.
update_option($option_name, $newvalue);
Updates or creates an option value in the database (note that add_option does not have to be called if you do not want to use the $deprecated or $autoload parameters).
$option_name
Required (string). Name of the option to update.
$newvalue
Required. (string|array|object) The new value for the option.

Pannelli di Amministrazione

Assuming that your Plugin has some options stored in the WordPress database (see section above), you will probably want it to have an administration panel that will enable your Plugin users to view and edit option values. The methods for doing this are described in Adding Administration Menus.

Tradurre in altre lingue il tuo Plugin

Once you have the programming for your Plugin done, another consideration (assuming you are planning on distributing your Plugin) is internationalization. Internationalization is the process of setting up software so that it can be localized; localization is the process of translating text displayed by the software into different languages. WordPress is used all around the world, so it has internationalization and localization built into its structure, including localization of Plugins.

Please note that language files for Plugins ARE NOT automatically loaded. Add this to the Plugin code to make sure the language file(s) are loaded:

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

To fetch a string simply use __('String name','your-unique-name'); to return the translation or _e('String name','your-unique-name'); to echo the translation. Translations will then go into your plugin's /languages folder.

It is highly recommended that you internationalize your Plugin, so that users from different countries can localize it. There is a comprehensive reference on internationalization, including a section describing how to internationalize your plugin, at I18n for WordPress Developers.

Aggiornamento del tuo Plugin

This section describes the necessary steps to update your Plugin when you host it on https://wordpress.org/plugins/, including details about using Subversion (SVN) with wordpress.org.

Assuming you have already submitted your Plugin to the WordPress Plugin Repository, over time you will probably find the need, and hopefully the time, to add features to your Plugin or fix bugs. Work on these changes and commit the changes to the trunk of your plugin as often as you want. The changes will be publicly visible, but only to the technically-minded people checking out your Plugin via SVN. What other users download through the website or their WordPress Plugin administration will not change.

When you're ready to release a new version of the Plugin:

  • Make sure everything is committed and the new version actually works. Pay attention to all WordPress versions your Plugin supports and try to test it with all of them. Don't just test the new features; also make sure you didn't accidentally break some older functionality of the Plugin.
  • Change the version number in the header comment of the main PHP file to the new version number (in the trunk folder).
  • Change the version number in the 'Stable tag' field of the readme.txt file (in the trunk folder).
  • Add a new sub-section in the 'changelog' section of the readme.txt file, briefly describing what changed compared to the last release. This will be listed on the 'Changelog' tab of the Plugin page.
  • Commit these changes.
  • Create a new SVN tag as a copy of trunk, following this guide.

Give the system a couple of minutes to work, and then check the wordpress.org Plugin page and a WordPress installation with your Plugin to see if everything updated correctly and the WordPress installation shows an update for your Plugin (the update checks might be cached, so this could take some time -- try visiting the 'available updates' page in your WordPress installation).

Troubleshooting:

  • The Plugin's page on wordpress.org still lists the old version. Have you updated the 'stable tag' field in the trunk folder? Just creating a tag and updating the readme.txt in the tag folder is not enough!
  • The Plugin's page offers a zip file with the new version, but the button still lists the old version number and no update notification happens in your WordPress installations. Have you remembered to update the 'Version' comment in the main PHP file?
  • For other problems check Otto's good write-up of common problems: The Plugins directory and readme.txt files

Suggerimenti per lo sviluppo di Plugins

This last section contains various suggestions regarding Plugin development.

  • The code of a WordPress Plugin should follow the WordPress Coding Standards. Please consider the Inline Documentation Standards as well.
  • All the functions in your Plugin need to have unique names that are different from functions in the WordPress core, other Plugins, and themes. For that reason, it is a good idea to use a unique function name prefix on all of your Plugin's functions. A far superior possibility is to define your Plugin functions inside a class (which also needs to have a unique name).
  • Do not hardcode the WordPress database table prefix (usually "wp_") into your Plugins. Be sure to use the $wpdb->prefix variable instead.
  • Database reading is cheap, but writing is expensive. Databases are exceptionally good at fetching data and giving it to you, and these operations are (usually) lightning quick. Making changes to the database, though, is a more complex process, and computationally more expensive. As a result, try to minimize the amount of writing you do to the database. Get everything prepared in your code first, so that you can make only those write operations that you need.
  • Use WordPress' APIs instead of using direct SQL where possible. For example, use get_posts() or new WP_Query() instead of SELECT * FROM {$wpdb->prefix}_posts.
  • Use the existing database tables instead of creating new custom tables if possible. Most use-cases can be accomplished with custom post types and meta data, custom taxonomy and/or one of the other standard tables and using the standard tables provides a lot of UI and other functionality "for free." Think very carefully before adding a table because it adds complexity to your plugin that many users and site builders prefer to avoid.
  • SELECT only what you need. Even though databases fetch data blindingly fast, you should still try to reduce the load on the database by only selecting that data which you need to use. If you need to count the number of rows in a table don't SELECT * FROM, because all the data in all the rows will be pulled, wasting memory. Likewise, if you only need the post_id and the post_author in your Plugin, then just SELECT those specific fields, to minimize database load. Remember: hundreds of other processes may be hitting the database at the same time. The database and server each have only so many resources to spread around amongst all those processes. Learning how to minimize your Plugin's hit against the database will ensure that your Plugin isn't the one that is blamed for abuse of resources.
  • Eliminate PHP errors in your plugin. Add define('WP_DEBUG', true); to your wp-config.php file, try all of your plugin functionality, and check to see if there are any errors or warnings. Fix any that occur, and continue in debug mode until they have all been eliminated.
  • Try not to echo <script> and <style> tags directly - instead use the recommended wp_enqueue_style() and wp_enqueue_script() functions. They help eliminate including duplicate scripts and styles as well as introduce dependency support. See posts by the following people for more info: Ozh Richard, Artem Russakovskii, and Vladimir Prelovac.

Risorse Esterne