Sviluppo Plugin: Gettiamo le Basi

In questo articolo vedremo quali sono le basi solide che un plugin deve avere, parleremo delle regole per assegnare nomi alle funzioni, dell’organizzazione dei file all’interno della directory di un plugin e della determinazione dei path. Iniziamo!

Requisiti per i plugin

Il sistema di plugin di WordPress è molto flessibile e permette di avere plugin composti da un solo file o una directory con una serie di file. Vediamo quali sono i consigli e le best practices di base.

Definizione del nome del plugin

Una scelta non banale è la definizione del nostro plugin, in quanto dovrà essere unico e una delle best practices è l’utilizzo del nome della nostra attività in abbinamento con la funzionalità principale che il plugin offre. Ad esempio se sto programmando un plugin per la gestione della cache, un valido nome potrebbe essere: Developress Cache System“.

Utilizzo di una cartella

Anche se il sistema plugin di WordPress permette la creazione di plugin formati da un solo file o, in genere, plugin senza directory e sempre buona regola lavorare con le cartelle e utilizzare, ad esempio, una cartella per i CSS, una per JS e altre per tipologia (o ruolo). Anche in questo caso è buona regola utilizzare come nome della cartella, un nome unico, sintetico e in minuscolo che non dovrà contenere spazi, trattini, lettere maiuscole e contenere, in generale, caratteri alfanumerici. Inoltre il nome della directory deve coincidere con il text domain in particolare quando il plugin è destinato per essere tradotto e per essere caricato nel repository ufficiale. Quindi riprendendo l’esempio precedente, un nome della directory corretto è “Developress Cache System”.

Best practices

Come per la programmazione di qualsiasi software o script, i programmatori devono seguire un insieme di regole per avere codice organizzato, pulito e facilmente comprensibile anche da parte di altri programmatori. Vediamo alcune best practices.

Nome delle funzioni

Per evitare conflitti tra funzioni e quindi errori all’interno di WordPress durante lo sviluppo del nostro plugin è necessario assegnare nomi unici alle funzioni. Ad esempio se nominiamo una funzione get_post() questa andrà in conflitto con WordPress in quanto già esiste e si crea un fatal error. Quindi scrivere codice di qualità significa anche non creare conflitti con quanto creato da altri programmatori; il metodo migliore per evitare conflitti è quello di utilizzare un prefisso (esempio develop_) o togliere gli spazi tra i nomi utilizzando la funzione namespace. Quindi una funzione tipo

get_post()

diventerà

develop_get_post()

Per evitare conflitti con altre funzioni è possibile utilizzare la funzione namespace di PHP che ci permette di creare nomi unici per le nuove funzioni, eliminando gli spazi tra le parole, in modo tale da evitare conflitti con i codici scritti da altri programmatori. Quindi nel nostro esempio: Developress Cache System diventerà DevelopressCacheSystem.

namespace DevelopressCacheSystem;

  class Setup {
        public function boot() {}
}

Questi non sono i soli casi in cui dobbiamo fare queste considerazioni ma è necessario prevenire conflitti con i nomi delle funzioni anche per l’aggiunta delle opzioni nel database e il caricamento dei file JavaScript. In questi ultimi casi è importante utilizzare il prefisso: developress_cache_system_option_name e il prefisso per gli script: developress-cache-system-script-name.

Organizzazione dei file in un plugin

In fase di sviluppo di un plugin è di primaria importanza riflettere su come organizzare i file al suo interno  ed avere da subito una struttura solida, in modo tale da aggiungere agevolmente nuove funzionalità. Il file principale e l’unico richiesto per ogni plugin è file PHP primario. Questo file può essere chiamato in qualunque modo e deve risiedere nella directory del plugin. Ad esempio se il file primario è plugin.php dovrà essere collocato qui: developress-cache-system/plugin.php. Alcuni programmatori preferiscono chiamare il file PHP primario con il nome del plugin developress-cache-system.php, si tratta di una scelta e non ci sono regole scritte per scegliere l’uno o l’altro, importante è sempre avere chiaro lo schema dei nomi.

Se abbiamo intenzione di sviluppare un plugin più elaborato che richiede  molti file, ad esempio JavaScript, è buona pratica mantenere il file primario PHP nella root principale del plugin e gli altri file in sottocartelle (ad eccezione del file unistall.php).

Plugin Header

Affinchè WordPress riconosca un plugin, il file PHP primario del plugin, deve avere alcune righe di codice PHP che costituiscono l’header all’inizio del file e che comunicano al CMS che si tratta di un plugin.

<?php
/**
 * Plugin Name: Developress Cache System
 * Plugin URI:  https://esempio.it
 * Description:  Attiva un sistema di cache su tutto il sito web.
* Version: 1.0.0
* Requires at least: 5.3
* Requires PHP: 5.6
* Author:      Developress
* Author URI:  htts://www.developress.it
* License: GPL v2 or later
* Text Domain: developr
 */

Determiniamo i PATHS (percorsi dei file)

Un programmatore non conosce l’URL alla quale un utente installa WordPress quindi è necessario non impostare un path di URL specifico. Ci sono due tipologie di path che possiamo prendere in considerazione quando costruiamo un plugin per WordPress. Il primo è Local Path e il secondo è URL paths che è necessario per il caricamento dei file JavaScript, CSS e altri. Dal momento che WordPress permette di spostare la directory wp-content (dove sono collocati i plugin) in qualsiasi altro posto (URL) nel server, è importante utilizzare le funzioni standard di WordPress per determinare il path corretto.

Local Paths

Local paths si riferiscono alle posizioni sul server. PHP fornisce metodi veloci per determinare un path per qualunque situazione.

<?php
     $path = plugin_dir_path ( $file );
?>

$file (stringa, required): nome del file nella directory attuale. Di seguito vediamo una funzione che restituisce la directory corrente del file:

<?php
echo plugin_dir_path(__FILE__);
?>

L’output dell’esempio sopra è un qualcosa di simile a:

/public_html/wp-content/plugins/developr

Qualunque file può essere passato in questa funzione. Se passiamo __FILE__ dal file PHP primario, avremo il path della root del plugin. Ipotizzando di dovere caricare il file:

/src/functions.php possiamo usare questo codice:

<?php
include plugin_dir_path( __FILE__ )  .  '/src/functions.php'
?>

Una pratica diffusa è di archiviare questo path come variabile o costante nel file primario del plugin per avere un accesso rapido alla root del plugin:

<?php
define ( 'DEVELOPR_DIR'), plugin_dir_path ( __FILE__ ) );
?>

Questo permette da la possibilità di fare riferimento a DEVELOPR in qualsiasi momento e in ogni posizione all’interno del plugin.

URL paths

I riferimenti alle URL paths non sono il metodo consigliato per determinare il percorso di un file. Uno dei casi più ricorrenti di utilizzo dei path URL è per determinare il percorso di un file JavaScript, CSS o di una immagine all’interno del nostro plugin. WordPress fornisce la funzione:

<?php
   $url = plugin_dir_url (  $file  );
?>

$file: è il nome del file nel path della directory corrente. Facciamo un esempio:

<?php
echo plugin_dir_url (  __FILE__ );
?>

Il codice sopra restituisce il seguente tipo di URL:

Se vogliamo determinare il path di un file JS presente qui: /public/js/esempio.js nel nostro plugin, possiamo utilizzare questo codice:

<?php
$url  =  plugin_dir_url ( __FILE__ ) . 'public/js/esempio.js';
?>

In molti casi può tornarci utile determinare le URL di alcune sezioni del nostro sito web, di una pagina o directory. Vediamo alcune funzioni di WordPress molto utili:

• site_url(): è il path URL dove WordPress è stato installato
• home_url(): è il path URL della home page del sito web
• admin_url(): è il path URL del backend di WordPress
• rest_url(): è il path URL delle REST API
• includes_url(): è il path URL della cartella includes di WordPress
• content_url(): è il path URL della cartella content di WordPress

Conclusioni

In questo articolo abbiamo visto come impostare le basi per lo sviluppo di un plugin, dalle tecniche per assegnare nomi alle funzioni fino all’organizzazione dei file all’interno della directory del plugin e, in conclusione, abbiamo visto la gestione dei PATHS. All’interno della categoria “Plugin” puoi leggere altre guide sullo sviluppo di plugin con codici completi e spiegati passo dopo passo, puoi anche utilizzare la funzione di ricerca interno al sito web per argomenti più specifici.