Migliori Pratiche Oggettive per lo Sviluppo di Plugin?

Caricare Scripts/CSS con wp_enqueue_script e wp_enqueue_style

I plugin non dovrebbero caricare/tentare di caricare versioni duplicate di file JS/CSS, specialmente jQuery e altri file JS inclusi nel Core di WordPress.

I plugin dovrebbero sempre utilizzare wp_enqueue_script e wp_enqueue_style quando collegano file JS e CSS e mai direttamente tramite tag <script>.

Correlati

• Riutilizzare funzioni esistenti

Supporto I18n

Tutte le stringhe di output dovrebbero essere collegate a un dominio di testo appropriato per consentire l'internazionalizzazione da parte di parti interessate, anche se lo sviluppatore non è interessato a tradurre il proprio plugin.

Nota che è molto importante caricare i file di lingua durante l'azione init in modo che l'utente possa agganciarsi all'azione.

Consulta il Codex: I18n per sviluppatori WordPress

E anche questo articolo: Caricare correttamente i file di lingua di WP.

Da WordPress 4.6+

WP 4.6 ha modificato l'ordine di caricamento e le posizioni verificate, rendendolo molto più semplice per sviluppatori e utenti.

Considerando un plugin con un dominio di testo 'my-plugin', WordPress ora cercherà PRIMA un file di traduzione in:
/wp-content/languages/plugins/my-plugin-en_US.mo

Se non lo trova, cercherà dove il plugin gli indica di cercare (di solito nella cartella 'language' del plugin se si segue il codex):
/wp-content/plugins/my-plugin/languages/my-plugin-en_US.mo

Infine, se non viene trovato alcun file di lingua, controllerà la posizione predefinita di:
/wp-content/languages/my-plugin-en_US.mo

Il primo controllo è stato aggiunto in 4.6 e offre agli utenti un luogo definito per aggiungere un file di lingua, poiché prima avrebbero bisogno di sapere dove lo sviluppatore aveva aggiunto il file di lingua, ora l'utente ha solo bisogno di conoscere il dominio di testo del plugin: /wp-content/languages/plugins/TEXTDOMAIN-LOCAL.mo

Di seguito il vecchio metodo (Non rilevante da WP 4.6+)

[...]
Infine, vorrei sottolineare che è importante caricare i file di lingua personalizzati dell'utente da WP_LANG_DIR prima di caricare i file di lingua forniti con il plugin. Quando vengono caricati più file mo per lo stesso dominio, verrà utilizzata la prima traduzione trovata. In questo modo i file di lingua forniti dal plugin serviranno come fallback per le stringhe non tradotte dall'utente.

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // Il filtro "plugin_locale" è utilizzato anche in load_plugin_textdomain()
    $locale = apply_filters( 'plugin_locale', get_locale(), $domain );

    load_textdomain( 
            $domain, 
            WP_LANG_DIR . '/my-plugin/' . $domain . '-' . $locale . '.mo' 
    );
    load_plugin_textdomain( 
            $domain, 
            FALSE, 
            dirname( plugin_basename(__FILE__) ) . '/languages/' 
    );
}

Assicurati che i Plugin non Generino Errori con WP_DEBUG

Testa sempre i tuoi plugin con WP_DEBUG attivato e idealmente tienilo attivo durante tutto il processo di sviluppo. Un plugin non dovrebbe generare NESSUN errore con WP_DEBUG attivo. Questo include notifiche di funzioni deprecate e indici non controllati.

Per attivare il debug, modifica il tuo file wp-config.php impostando la costante WP_DEBUG su true. Consulta la Codex sul Debug per maggiori dettagli.

Utilizza Prima le Funzioni Esistenti nel Core di WordPress

Se possibile: usa le funzioni già incluse nel core di WordPress invece di scriverne di nuove. Sviluppa funzioni PHP personalizzate solo quando non esiste una funzione appropriata già presente nel core di WordPress.

Un vantaggio è che puoi usare le "notifiche di deprecazione" per monitorare facilmente le funzioni che dovrebbero essere sostituite. Un altro vantaggio è che gli utenti possono consultare la documentazione della funzione nel Codex e capire meglio cosa fa il plugin, anche se non sono sviluppatori PHP esperti.

Correlati

• Supporto I18n
• Carica Scripts/CSS con wp_enqueue_script e wp_enqueue_style
• Offri Form Estensibili

La disinstallazione dovrebbe rimuovere tutti i dati di un plugin

Quando viene rimosso da un'installazione WordPress, un plugin dovrebbe eliminare tutti i file, cartelle, voci del database e tabelle che ha creato, così come i valori delle opzioni che ha generato.

I plugin possono offrire un'opzione per esportare/importare le impostazioni, in modo che queste possano essere salvate al di fuori di WordPress prima della cancellazione.

Correlati

• La disattivazione non dovrebbe causare la perdita di dati

Prevenire SQL Injection con i Dati di Input

Un plugin dovrebbe sanificare tutti gli input utente ottenuti direttamente o indirettamente (ad esempio tramite $_POST o $_GET) prima di utilizzare i valori di input per interrogare il database MySQL.

Vedi: Formattazione delle istruzioni SQL.

Utilizza una classe e codice PHP orientato agli oggetti

Non c'è alcun motivo per non scrivere codice PHP pulito e orientato agli oggetti. PHP4 non è più supportato dal 2008. Certo, potresti prefissare tutti i nomi delle tue funzioni per ottenere nomi_di_funzioni_lunghissimi_con_molti_underscore, ma è molto più semplice scrivere una semplice classe e raggruppare tutto al suo interno. Inoltre, inserisci la tua classe in un file separato e denominarlo in modo appropriato per poterlo estendere e mantenere facilmente:

// in functions.php
require 'inc/class-my-cool-plugin.php';
new MyCoolPlugin();

// in inc/class-my-cool-plugin.php
class MyCoolPlugin {
    function __construct() {
        // aggiungi hook dei filtri, wp_enqueue_script, ecc.
        
        // Per assegnare un metodo dalla tua classe a una funzione
        // di WP, fai qualcosa come questo
        add_action('admin_menu', [$this, "admin"]);
    }
    
    public function admin() {
        // metodi pubblici, per l'uso al di fuori della classe
        // Nota che i metodi utilizzati in altre funzioni di WP
        // (come add_action) dovrebbero essere pubblici
    }
    
    private function somethingelse() {
        // metodi che usi solo all'interno di questa classe
    }
}

Prefissa tutti gli elementi nello spazio globale dei nomi

Un plugin dovrebbe prefissare correttamente TUTTI gli elementi nello spazio globale dei nomi (costanti, funzioni, classi, variabili, e anche elementi come tassonomie personalizzate, tipi di post, widget, ecc.). Ad esempio, non creare una funzione chiamata init(); invece, chiamala qualcosa come jpb_init().

È comune utilizzare un prefisso di tre o quattro lettere davanti ai nomi o fare uso della funzionalità Namespace di PHP. Confronta: Prefisso a singola lettera per le costanti di classe PHP?

Correlati

• Lo spazio globale dei nomi è una risorsa limitata

La disattivazione non dovrebbe causare la perdita di dati

Un plugin non dovrebbe eliminare alcun dato in seguito alla disattivazione.

Correlati

• La disinstallazione dovrebbe rimuovere tutti i dati del plugin

Includi solo i file di cui hai bisogno...

Se sei nel front end, non includere codice relativo all'area di amministrazione.

Comunicare la Perdita di Dati durante la Disinstallazione del Plugin

Durante la disinstallazione, un plugin dovrebbe avvisare l'utente che eliminerà i suoi dati e ricevere una conferma che l'utente accetti l'eliminazione dei dati prima di procedere. Inoltre, un plugin dovrebbe offrire all'utente la possibilità di conservare i dati durante la disinstallazione. (Questa idea proviene da @EAMann.)

Correlati

• La disinstallazione dovrebbe rimuovere tutti i dati del plugin
• La disattivazione non dovrebbe causare la perdita di dati

Consenti la modifica del nome della cartella del plugin

/plugins/nomeplugin/{vari}

Il "nomeplugin" utilizzato per la cartella dovrebbe sempre poter essere modificato.

Questo viene normalmente gestito definendo delle costanti e utilizzandole in modo coerente in tutto il plugin.

Inutile dire che molti plugin popolari peccano in questo.

Correlati:

• plugins_url() per collegare facilmente alle risorse incluse nel plugin.

Minimizzare i Nomi Aggiunti allo Spazio dei Nomi Globale

Un plugin dovrebbe ridurre il proprio impatto il più possibile minimizzando il numero di nomi che aggiunge allo spazio dei nomi globale.

Questo può essere fatto incapsulando le funzioni del plugin in una classe o utilizzando la funzionalità degli spazi dei nomi di PHP. Anche prefissare tutto può aiutare, ma non è così flessibile.

Oltre alle funzioni e alle classi, un plugin non dovrebbe introdurre variabili globali. L'uso delle classi normalmente le rende obsolete e semplifica la manutenzione del plugin.

Correlati

• Prefissare Correttamente

Utilizza la gestione degli errori integrata in WordPress

Non limitarti a fare un semplice return; se qualche input dell'utente è sbagliato. Fornisci loro alcune informazioni su cosa è stato fatto male.

function some_example_fn( $args = array() ) 
{
    // Se il valore non è stato impostato, costruisci un messaggio di errore
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'Hai dimenticato di specificare %1$s per la tua funzione. %2$s Errore attivato in %3$s alla riga %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // interrompi e stampa il messaggio di errore e il codice - solo per gli amministratori!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Errore del Tema: Argomento Mancante' );

    // Altrimenti, se nessun errore è stato attivato, continua...
}

Un unico oggetto errore per tutti

Puoi impostare un oggetto errore globale per il tuo tema o plugin durante il bootstrap:

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Prendi il nome del tema come ID dell'errore:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // qualsiasi cosa, ecc...
}
add_action( 'after_setup_theme', 'bootstrap_the_theme' );

Successivamente puoi aggiungere errori illimitati su richiesta:

function some_theme_fn( $args )
{
    global $prefix_error, $prefix_theme_name;
    $theme_data = wp_get_theme();
    if ( ! $args['whatever'] && current_user_can( 'manage_options' ) ) // qualche valore richiesto non impostato
        $prefix_error->add( $prefix_theme_name, sprintf( 'La funzione %1$s richiede l\'argomento %2$s impostato.', __FUNCTION__, '$args[\'whatever\']' ) );

    // continua la funzione...
}

Quindi puoi recuperarli tutti alla fine del tuo tema. In questo modo non interrompi il rendering della pagina e puoi comunque mostrare tutti i tuoi errori per lo sviluppo

function dump_theme_errors()
{
    global $prefix_error, $prefix_theme_name;

    // Non sei un amministratore? OPPURE: Nessun errore?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

    $theme_errors = $prefix_error->get_error_messages( $prefix_theme_name );
    echo '<h3>Errori del Tema</h3>';
    foreach ( $theme_errors as $error )
        echo "{$error}\n";
}
add_action( 'shutdown', 'dump_theme_errors' );

Puoi trovare ulteriori informazioni su questa domanda. Un ticket correlato per sistemare il "funzionamento insieme" di WP_Error e wp_die() è linkato da lì e un altro ticket seguirà. Commenti, critiche e simili sono apprezzati.

Usa l'API delle Impostazioni prima di add_option

Invece di aggiungere opzioni al database tramite la funzione add_option, dovresti memorizzarle come un array utilizzando l'API delle Impostazioni che si occupa di tutto per te.

Usa l'API delle Modifiche del Tema prima di add_option

L'API delle Modifiche è una struttura piuttosto semplice e un modo sicuro che consente di aggiungere e recuperare opzioni. Tutto viene salvato come valore serializzato nel tuo database. Facile, sicuro e semplice.

Commentare utilizzando PhpDoc

La migliore pratica è vicina allo stile PhpDoc. Se non utilizzi un IDE come "Eclipse", puoi semplicemente dare un'occhiata al Manuale PhpDoc.

Non è necessario sapere esattamente come funziona. Gli Sviluppatori Professionisti possono comunque leggere il codice e hanno solo bisogno di questo come riepilogo. I programmatori hobbisti e gli utenti potrebbero apprezzare il modo in cui lo spieghi allo stesso livello di conoscenza.

Proteggere la Privacy degli Utenti dei Plugin

(Precedentemente: Comunicazione API Anonima)

Se un plugin comunica con un sistema esterno o un'API (ad esempio un servizio web), dovrebbe farlo in modo anonimo o fornire all'utente un'opzione anonima che garantisca che nessun dato relativo all'utente del plugin venga trasmesso a terze parti in modo incontrollato.

Ospita i Plugin su WordPress.org

Utilizza il repository SVN fornito su WordPress.org per ospitare i plugin. Offre un'esperienza di aggiornamento più semplice agli utenti e, se non hai mai usato SVN prima, ti permette di comprenderlo utilizzandolo in un contesto che giustifica il suo impiego.

Fornire il Controllo degli Accessi Utilizzando i Permessi

In molti casi, gli utenti potrebbero non volere che tutti abbiano accesso alle aree create dal tuo plugin, specialmente con plugin che eseguono operazioni complesse multiple. Un singolo controllo delle capacità hardcoded potrebbe non essere sufficiente.

Come minimo, assicurati di avere controlli appropriati delle capacità per tutti i diversi tipi di procedure per cui il tuo plugin può essere utilizzato.

Organizza il tuo codice

È sempre difficile leggere codice che non è scritto nell'ordine in cui viene eseguito. Prima include/require, define, wp_enqueue_style & _script, ecc., poi le funzioni di cui il plugin/theme ha bisogno e infine il builder (ad esempio schermata di amministrazione, elementi che si integrano nel tema, ecc.).

Cerca di separare elementi come CSS e JS nelle loro cartelle dedicate. Cerca anche di fare lo stesso con funzioni che sono solo helper, come quelle per appiattire array e simili. Mantenere il file "principale" il più pulito e leggibile possibile è un modo per aiutare utenti, sviluppatori e te stesso, quando proverai ad aggiornare tra un anno e non avrai visto il codice per molto tempo.

È anche utile avere una struttura che ripeti spesso, così da ritrovarti sempre. Sviluppare in una struttura conosciuta su diversi progetti ti darà il tempo di migliorarla e anche se il tuo cliente passa a un altro sviluppatore, non sentirai mai "ha lasciato il caos". Questo costruisce la tua reputazione e dovrebbe essere un obiettivo a lungo termine.

Importa / Esporta Impostazioni del Plugin

Non è così comune tra i plugin, ma se il tuo plugin ha (alcune) impostazioni, dovrebbe fornire la possibilità di Importare/Esportare dati come configurazione e input utente.

Importa/Esporta migliora l'usabilità di un plugin.

Un esempio di plugin che ha questa funzionalità di importazione ed esportazione (e anche un meccanismo di annullamento) è Breadcrumb NavXT (Plugin WordPress) (piena trasparenza: c'è un po' di mio codice lì dentro, ma la maggior parte è stato fatto da mtekk).

Correlati

• La disinstallazione dovrebbe rimuovere tutti i dati del plugin
• La disattivazione non dovrebbe causare la perdita di dati

Morire con stile

Termina in modo elegante Tutte le funzioni di un plugin (e anche dei temi) dovrebbero utilizzare wp_die() nei punti critici per offrire all'utente qualche informazione su ciò che è accaduto. Gli errori PHP sono fastidiosi e wp_die può fornire all'utente un messaggio ben formattato su cosa il plugin (o loro) ha fatto di sbagliato. Inoltre, se l'utente ha il debug disattivato, il plugin si interromperà semplicemente.

L'uso di wp_die() aiuta anche a garantire che i tuoi plugin/temi siano compatibili con la suite di test di WordPress.

• Usa la gestione degli errori di WP

Fornisci schermate di aiuto per gli utenti

È più gentile rispondere RTFM (clicca su aiuto) piuttosto che dover rispondere alla stessa domanda ripetutamente.

/**
  * Aggiungi aiuto contestuale per questa schermata
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>Plugin WordPress - Schermata A</h3>';
        $rtfm .= '<p>Ecco alcuni suggerimenti: dona a me ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

aggiornamento / nota: (vedi commenti di kaiser): l'esempio sopra va usato in una classe

Offri Form Estensibili

Quando un plugin offre la possibilità di inserire dati, dovrebbe sempre includere un hook alla fine, appena prima del pulsante "invia" e/o "resetta", in modo che gli sviluppatori possano facilmente estendere il form non solo con campi, ma anche con pulsanti aggiuntivi.

Vedi: Settings API

Correlati

• Usa Azioni e Filtri
• Riutilizza funzioni esistenti
• Supporto I18n

Includi sempre le funzioni tramite Hook, non direttamente.

Esempio:

• Non utilizzare new per includere la classe del plugin senza hook

• Utilizza l'Hook plugins_loaded

  // aggiungi la classe a WP                                   
  function my_plugin_start() {                                                               
      new my_plugin();   
  }                                                        
  add_action( 'plugins_loaded', 'my_plugin_start' );
  

Aggiornamento: un piccolo esempio live: Plugin-svn-trunk-page e un esempio pseudo

//evita chiamate dirette a questo file dove i file core di wp non sono presenti
if (!function_exists ('add_action')) {
        header('Status: 403 Forbidden');
        header('HTTP/1.1 403 Forbidden');
        exit();
}

if ( !class_exists( 'plugin_class' ) ) {
    class plugin_class {

        function __construct() {
        }

    } // fine classe

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // fine class_exists

Puoi anche caricare via mu_plugins_loaded su installazioni multisite, consulta il codex per i riferimenti alle azioni: http://codex.wordpress.org/Plugin_API/Action_Reference Qui puoi anche vedere come includere WP con questo hook: http://adambrown.info/p/wp_hooks/hook/plugins_loaded?version=2.1&file=wp-settings.php Lo uso molto spesso e non è così difficile e precoce, meglio di un hard new class();

La descrizione del tuo plugin dovrebbe dettagliare accuratamente le funzioni del tuo plugin. Ci sono 10 plugin per i post in evidenza. Tutti mostrano i post in evidenza, ma molti hanno funzionalità diverse. Dovrebbe essere facile confrontare il tuo plugin con plugin simili leggendo la descrizione.

Dovresti evitare di vantarti di quanto sia semplice il tuo plugin a meno che non sia veramente molto basilare. Dovresti includere nella descrizione link utili come quello alle impostazioni.

Plugin con Licenza Compatibile con la GPL

I plugin e i temi dovrebbero essere rilasciati con una licenza compatibile con WordPress. Ciò consente la loro ridistribuzione insieme a WordPress come "programma". Una licenza raccomandata è la GPL. Assicurati che tutte le librerie di codice incluse nel plugin siano compatibili con la stessa licenza.

(Questo ha rappresentato un problema ed è stato un serio punto di dibattito sia in passato che nel presente.)

Minimizzare gli Effetti Collaterali delle Fonti di Dati Remote e dei Webservice

Un Plugin dovrebbe Memorizzare nella Cache/Proteggere i Webservice e/o le richieste XMLRPC/SOAP attraverso un livello di caching/fornitore di dati se li utilizzi, in modo da non far attendere le richieste frontend per una (lenta) risposta del webservice.

Ciò include il download di feed RSS e altre pagine. Progetta i tuoi plugin in modo che richiedano i dati in background.

Un possibile PASSAGGIO è (prendiamo come esempio l'invio a ping.fm): Crea una tabella buffer, ad esempio: ping_fm_buffer_post( date, time, message, submitted_time, status )

1. Ogni volta che vuoi inviare un aggiornamento a ping.fm, aggiungilo a questa tabella.
2. Ora, dobbiamo creare un plugin per gestire questi dati. Questo plugin verrà eseguito tramite crontab per verificare ogni aggiornamento non ancora inviato
3. Poiché abbiamo questa tabella, possiamo anche elencare ogni messaggio inviato a ping.fm e verificare lo stato di ogni post. Nel caso ci siano problemi dal lato di ping.fm, possiamo reinviarlo.

Utilizza gli Standard di Codifica di WordPress

http://codex.wordpress.org/WordPress_Coding_Standards

Sai quanto è più semplice aggiornare un codice su cui hai lavorato rispetto a un codice realizzato da qualcun altro? Gli standard di codifica rendono più facile per qualsiasi sviluppatore che lavora a un progetto comprendere cosa sta succedendo.

Sappiamo che il tuo plugin o tema è tuo, e il modo in cui interrompi le righe e aggiungi le parentesi graffe è un'espressione della tua individualità. Ogni indentazione è un'affermazione ponderata con cura. Ma con il tuo codice personalizzato, stai contribuendo a WordPress, anche se il tuo codice non fa parte dell'applicazione core. Gli standard di codifica aiutano gli sviluppatori a familiarizzare rapidamente con il tuo codice.