Practici Objektive Recomandate pentru Dezvoltarea de Plugin-uri?

Încărcarea scripturilor/CSS cu wp_enqueue_script și wp_enqueue_style

Plugin-urile nu ar trebui să încarce/să încerce să încarce versiuni duplicate de fișiere JS/CSS, în special jQuery și alte fișiere JS incluse în WP Core.

Plugin-urile ar trebui să folosească întotdeauna wp_enqueue_script și wp_enqueue_style când leagă fișiere JS și CSS și niciodată direct prin tag-uri <script>.

Legături relevante

• Reutilizarea funcțiilor existente

Suport I18n

Toate șirurile de ieșire ar trebui să fie legate de un domeniu de text adecvat pentru a permite internaționalizarea de către părțile interesate, chiar dacă dezvoltatorul nu are interes să-și traducă propriul plugin.

Rețineți că este foarte important să încărcați fișierele de limbă în timpul acțiunii init, astfel încât utilizatorul să se poată conecta la acțiune.

Consultați Codex: I18n pentru dezvoltatorii WordPress

Și de asemenea acest articol: Încărcarea corectă a fișierelor de limbă WP.

Începând cu WordPress 4.6+

WP 4.6 a schimbat ordinea de încărcare și locațiile verificate, ceea ce a făcut mult mai ușor pentru dezvoltatori și utilizatori.

Având în vedere un plugin cu un domeniu de text 'my-plugin', WordPress va căuta ACUM ÎNTÂI un fișier de traducere în:
/wp-content/languages/plugins/my-plugin-en_US.mo

Dacă nu găsește unul acolo, va căuta unul acolo unde pluginul îi spune să se uite (de obicei în folderul 'language' al pluginului dacă urmăriți codex-ul):
/wp-content/plugins/my-plugin/languages/my-plugin-en_US.mo

În cele din urmă, dacă nu este găsit niciun fișier de limbă, va verifica locația implicită:
/wp-content/languages/my-plugin-en_US.mo

Prima verificare a fost adăugată în 4.6 și oferă utilizatorilor un loc definit pentru a adăuga un fișier de limbă, deoarece înainte ar fi nevoie să știe unde dezvoltatorul a adăugat fișierul de limbă, acum utilizatorul trebuie doar să cunoască domeniul de text al pluginului: /wp-content/languages/plugins/TEXTDOMAIN-LOCAL.mo

Mai jos este vechiul mod (Nu este relevant începând cu WP 4.6+)

[...]
În cele din urmă, aș dori să subliniez că este important să încărcați fișierele de limbă personalizate ale utilizatorului din WP_LANG_DIR înainte de a încărca fișierele de limbă care vin cu pluginul. Atunci când sunt încărcate mai multe fișiere mo pentru același domeniu, prima traducere găsită va fi utilizată. În acest fel, fișierele de limbă furnizate de plugin vor servi ca o rezervă pentru șirurile netraduse de utilizator.

public function load_plugin_textdomain()
{
    $domain = 'my-plugin';
    // Filtrul "plugin_locale" este, de asemenea, utilizat în 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/' 
    );
}

Asigură-te că Plugin-urile Nu Generează Erori cu WP_DEBUG

Testează întotdeauna plugin-urile tale cu WP_DEBUG activat și, ideal, păstrează-l activ pe tot parcursul procesului de dezvoltare. Un plugin nu ar trebui să arunce NICI O eroare când WP_DEBUG este activat. Aceasta include notificări de funcții învechite și indecși neverificați.

Pentru a activa depanarea, editează fișierul wp-config.php astfel încât constanta WP_DEBUG să fie setată la true. Consultă Codex-ul despre Depanare pentru mai multe detalii.

Utilizează mai întâi funcțiile existente în nucleul WordPress

Dacă este posibil: folosește funcțiile existente incluse în nucleul WordPress în loc să scrii altele proprii. Dezvoltă funcții PHP personalizate doar atunci când nu există o funcție adecvată preexistentă în nucleul WordPress.

Unul dintre avantaje este că poți folosi "notificări de funcții depreciate" pentru a monitoriza ușor funcțiile care ar trebui înlocuite. Un alt avantaj este că utilizatorii pot consulta documentația funcției în Codex și pot înțelege mai bine ce face plugin-ul, chiar dacă nu sunt dezvoltatori PHP experimentați.

Articole conexe

• Suport I18n
• Încărcarea scripturilor/CSS cu wp_enqueue_script și wp_enqueue_style
• Oferă formulare extensibile

Dezinstalarea ar trebui să elimine toate datele unui plugin

La eliminarea dintr-o instalare WordPress, un plugin ar trebui să șteargă toate fișierele, folderele, intrările din baza de date și tabelele pe care le-a creat, precum și valorile opțiunilor adăugate.

Plugin-urile pot oferi o opțiune de export/import a setărilor, astfel încât acestea să poată fi salvate în afara WordPress înainte de ștergere.

Legături utile

• Dezactivarea nu ar trebui să provoace pierderea datelor

Prevenirea Injectării SQL cu Date de Intrare

Un plugin ar trebui să sanitizeze toate datele introduse de utilizator, obținute direct sau indirect (de exemplu prin $_POST sau $_GET) înainte de a folosi valorile introduse pentru a interoga baza de date MySQL.

Consultați: Formatarea declarațiilor SQL.

Folosește o clasă și cod PHP orientat pe obiecte

Nu există niciun motiv să nu scrii cod PHP curat, orientat pe obiecte. PHP4 nu este suportat din 2008. Desigur, poți prefixa toate numele funcțiilor pentru a ajunge la nume_de_funcții_foarte_lungi_cu_multe_underscore-uri, dar este mult mai ușor să scrii o simplă clasă și să grupezi totul în aceasta. De asemenea, pune clasa într-un fișier separat și numește-o corespunzător, astfel încât să poți extinde și întreține cu ușurință:

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

// în inc/class-my-cool-plugin.php
class MyCoolPlugin {
    function __construct() {
        // adaugă filtre, wp_enqueue_script, etc.
        
        // Pentru a atribui o metodă din clasă unei funcții WP
        // fă ceva de genul acesta
        add_action('admin_menu', [$this, "admin"]);
    }
    
    public function admin() {
        // metode publice, pentru utilizare în afara clasei
        // Reține că metodele utilizate în alte funcții WP
        // (cum ar fi add_action) ar trebui să fie publice
    }
    
    private function somethingelse() {
        // metode pe care le folosești doar în interiorul acestei clase
    }
}

Prefixează toate elementele din spațiul global

Un plugin ar trebui să prefixeze corespunzător TOATE elementele din spațiul global (constante, funcții, clase, variabile, chiar și lucruri precum taxonomii personalizate, tipuri de postări, widget-uri, etc.). De exemplu, nu creați o funcție numită init(); în schimb, denumiți-o ceva de genul jpb_init().

Este recomandat să folosiți un prefix de trei sau patru litere în fața numelor sau să utilizați Funcția PHP Namespace. Comparați: Prefix de o singură literă pentru constantele de clasă PHP?

Legături utile

• Spațiul global este o resursă limitată

Dezactivarea nu ar trebui să provoace pierderea de date

Un plugin nu ar trebui șteargă vreo parte din datele sale în urma dezactivării.

Legături conexe

• Dezinstalarea ar trebui să elimine toate datele plugin-ului

Includează doar fișierele de care ai nevoie...

Dacă ești în partea de front end, nu include cod care se referă la zona de administrare.

Anunțarea Pierderii de Date la Dezinstalarea Plugin-ului

La dezinstalare, un plugin ar trebui să anunțe utilizatorul că va șterge datele sale și să primească o confirmare că utilizatorul este de acord cu ștergerea datelor înainte de a o face. De asemenea, un plugin ar trebui să permită utilizatorului opțiunea de a păstra datele la dezinstalare. (Această idee aparține lui @EAMann.)

Legături relevante

• Dezinstalarea ar trebui să elimine toate datele plugin-ului
• Dezactivarea nu ar trebui să provoace pierderea datelor

Permiteți modificarea numelui folderului pluginului

/plugins/pluginname/{diverse}

Numele "pluginname" utilizat pentru folder ar trebui să poată fi întotdeauna schimbat.

Aceasta se realizează în mod normal prin definirea constantelor și utilizarea lor consecventă în întregul plugin.

Este inutil să spunem că multe pluginuri populare nu respectă această regulă.

Legături conexe:

• plugins_url() pentru legături ușoare către resursele incluse în plugin.

Minimizează Numărul de Nume Adăugate în Spațiul Global

Un plugin ar trebui să reducă impactul său cât mai mult posibil prin minimizarea numărului de nume pe care le adaugă în spațiul global.

Aceasta poate fi realizată prin încapsularea funcțiilor plugin-ului într-o clasă sau prin utilizarea funcției PHP de namespace-uri. Prefixarea tuturor elementelor poate ajuta de asemenea, dar nu este la fel de flexibilă.

Pe lângă funcții și clase, un plugin nu ar trebui să introducă variabile globale. Utilizarea claselor elimină de obicei nevoia acestora și simplifică întreținerea plugin-ului.

Legături asociate

• Prefixează corect

Folosește gestionarea erorilor încorporată în WordPress

Nu doar return; dacă unele date introduse de utilizator sunt greșite. Oferă-le informații despre ce s-a făcut greșit.

function some_example_fn( $args = array() ) 
{
    // Dacă valoarea nu a fost setată, construiește un mesaj de eroare
    if ( ! isset( $args['some_value'] ) )
        $error = new WP_Error( 'some_value', sprintf( __( 'Ai uitat să specifici %1$s pentru funcția ta. %2$s Eroare declanșată în %3$s la linia %4$s.', TEXTDOMAIN ), '$args[\'some_value\']', "\n", __FILE__, __LINE__ ) );

    // oprește execuția & afișează mesajul de eroare & codul - doar pentru administratori!
    if ( isset( $error ) && is_wp_error( $error ) && current_user_can( 'manage_options' ) ) 
        wp_die( $error->get_error_code(), 'Eroare Temă: Argument Lipsă' );

    // Altfel, dacă nu a fost declanșată nicio eroare, continuă...
}

O singură eroare (obiect) pentru toate

Poți configura un obiect global de eroare pentru tema sau pluginul tău în timpul inițializării:

function bootstrap_the_theme()
{
    global $prefix_error, $prefix_theme_name;
    // Ia numele temei ca ID de eroare:
    $theme_data = wp_get_theme();
    $prefix_theme_name = $theme_data->Name;
    $prefix_error = new WP_Error( $theme_data->Name );

    include // orice, etc...
}
add_action( 'after_setup_theme', 'bootstrap_the_theme' );

Ulterior poți adăuga nelimitat erori la cerere:

function some_theme_fn( $args )
{
    global $prefix_error, $prefix_theme_name;
    $theme_data = wp_get_theme();
    if ( ! $args['whatever'] && current_user_can( 'manage_options' ) ) // o valoare necesară nesetată
        $prefix_error->add( $prefix_theme_name, sprintf( 'Funcția %1$s necesită argumentul %2$s setat.', __FUNCTION__, '$args[\'whatever\']' ) );

    // continuă funcția...
}

Apoi le poți colecta pe toate la sfârșitul temei tale. Astfel nu întrerupi randarea paginii și poți totuși afișa toate erorile pentru dezvoltare

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

    // Nu ești administrator? SAU: Nu sunt erori?
    if ( ! current_user_can( 'manage_options' ) ! is_wp_error( $prefix_error ) )
        return;

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

Poți găsi informații suplimentare la această Întrebare. Un tichet legat de remedierea "colaborării" dintre WP_Error și wp_die() este legat de acolo și un alt tichet va urma. Comentariile, critica & altele sunt apreciate.

Folosește Settings API înainte de add_option

În loc să adaugi opțiuni în baza de date prin funcția add_option, ar trebui să le stochezi ca un array folosind Settings API, care se ocupă de toate detaliile pentru tine.

Folosește Theme Modifications API înainte de add_option

Modifications API este o structură destul de simplă și o modalitate sigură de a adăuga și prelua opțiuni. Totul este salvat ca valoare serializată în baza ta de date. Simplu, sigur și ușor.

Comentarea folosind PhpDoc

Cea mai bună practică este apropiată de stilul PhpDoc. Dacă nu folosești un IDE precum "Eclipse", poți consulta manualul PhpDoc.

Nu este necesar să înțelegi exact cum funcționează. Dezvoltatorii profesioniști pot citi codul oricum și au nevoie doar de acest rezumat. Utilizatorii pasionați sau hobbyști ar putea aprecia modul în care explici la același nivel de cunoștințe.

Protejarea confidențialității utilizatorilor plugin-urilor

(Anterior: Comunicare API anonimă)

Dacă un plugin comunică cu un sistem extern sau un API (de exemplu, un serviciu web), acesta ar trebui să facă acest lucru în mod anonim sau să ofere utilizatorului o opțiune anonimă care să asigure că nicio dată legată de utilizatorul plugin-ului nu este transmisă unei terțe părți în mod necontrolat.

Găzduiește Plugin-uri pe WordPress.org

Folosește depozitul SVN oferit de WordPress.org pentru a găzdui plugin-uri. Acesta oferă o experiență mai ușoară de actualizare pentru utilizatori, iar dacă nu ai folosit niciodată SVN până acum, te va ajuta să-l înțelegi prin utilizarea într-un context care justifică acest lucru.

Asigurați Controlul Accesului Prin Utilizarea Permisiunilor

În multe cazuri, utilizatorii pot dori să nu permită accesul tuturor în zonele create de plugin-ul lor, mai ales în cazul plugin-urilor care efectuează multiple operații complexe. O singură verificare a capacității hardcodate poate să nu fie suficientă.

Cel puțin, asigurați-vă că aveți verificări adecvate ale capacității pentru toate tipurile de proceduri pentru care poate fi utilizat plugin-ul dumneavoastră.

Organizează-ți codul

Întotdeauna este dificil să citești un cod care nu este scris în ordinea în care este executat. Mai întâi include/require, definiții, wp_enqueue_style & _script, etc., apoi funcțiile de care are nevoie plugin-ul/tema și la final constructorul (de ex. ecranul de administrare, elemente care se integrează în temă, etc.).

Încearcă să separi lucruri precum CSS și JS în foldere proprii. De asemenea, încearcă să faci același lucru cu funcțiile care sunt doar ajutoare, precum aplatizări de array și altele asemănătoare. Păstrarea fișierului "principal" cât mai curat și ușor de citit este o modalitate care ajută utilizatorii, dezvoltatorii și pe tine, când încerci să actualizezi peste un an și nu ai mai văzut codul de mult timp.

De asemenea, este bine să ai o structură pe care o repeți des, astfel încât să-ți găsești întotdeauna drumul. Dezvoltarea într-o structură cunoscută pe diferite proiecte îți va oferi timp să o îmbunătățești și chiar dacă clientul tău trece la un alt dezvoltator, nu vei auzi niciodată "a lăsat un haos". Acest lucru îți construiește reputația și ar trebui să fie un obiectiv pe termen lung.

Import / Export Setări Plugin

Nu este ceva foarte comun între plugin-uri, dar dacă plugin-ul tău are (unele) setări, ar trebui să oferă funcționalități de Import / Export pentru date precum configurația și input-ul utilizatorului.

Importul/Exportul îmbunătățește utilizabilitatea unui plugin.

Un exemplu de plugin care are astfel de funcționalități de import și export (precum și un mecanism de undo) este Breadcrumb NavXT (Plugin Wordpress) (informație completă: conține câteva linii de cod scrise de mine, dar majoritatea au fost realizate de mtekk).

Legături Utile

• Dezinstalarea ar trebui să șteargă toate datele plugin-ului
• Dezactivarea nu ar trebui să provoace pierdere de date

Încheiere stilată

oprirea într-un mod decent Toate funcțiile unui plugin (și chiar ale unei teme) ar trebui să utilizeze wp_die() în locurile critice pentru a oferi utilizatorului câteva informații despre ce s-a întâmplat. Erorile PHP sunt enervante, iar wp_die poate oferi utilizatorului un mesaj frumos stilizat despre ce a greșit pluginul (sau ei). În plus, dacă utilizatorul are depanarea dezactivată, pluginul pur și simplu se va opri.

Folosirea wp_die() ajută și la asigurarea compatibilității pluginurilor/temelor dumneavoastră cu suita de teste WordPress.

• Folosește gestionarea erorilor în WordPress

Oferă ecrane de ajutor pentru utilizatori

Este mai drăguț să răspunzi RTFM (apasă ajutor) decât să răspunzi la aceeași întrebare de mai multe ori.

/**
  * Adaugă ajutor contextual pentru acest ecran
  * 
  * @param $rtfm
  * @uses get_current_screen
  */ 
  function ContextualHelp( /*string*/ $rtfm) 
  { 
     $current_screen = get_current_screen();
     if ($current_screen->id == $this->_pageid) 
     {
        $rtfm .= '<h3>WordPress Plugin - Ecranul A</h3>';
        $rtfm .= '<p>Câteva sfaturi: donează-mi ' .
     }
     return $rtfm; 
  }
add_action('contextual_help', array($this,'ContextualHelp'),1,1);

actualizare / notă: (vezi comentariile de la kaiser): exemplul de mai sus trebuie utilizat într-o clasă

Oferă Formulare Extensibile

Când un plugin oferă posibilitatea de a introduce date, ar trebui să aibă întotdeauna un hook la final, chiar înainte de butonul "submit" și/sau "reset", astfel încât dezvoltatorii să poată extinde ușor formularul nu doar cu câmpuri, ci și cu butoane.

Vezi: Settings API

Conținut Relaționat

• Folosește Acțiuni și Filtre
• Reutilizează funcții existente
• Suport I18n

Includează întotdeauna funcțiile prin Hook, nu direct.

Exemplu:

• Nu utiliza pentru a include clasa pluginului prin new fără hook

• Folosește Hook-ul plugins_loaded

  // adaugă clasa în WP                                   
  function my_plugin_start() {                                                               
      new my_plugin();   
  }                                                        
  add_action( 'plugins_loaded', 'my_plugin_start' );
  

Actualizare: un mic exemplu live: Plugin-svn-trunk-page și un exemplu pseudo

//evită apelurile directe la acest fișier unde fișierele de bază wp nu sunt prezente
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() {
        }

    } // sfârșitul clasei

    function plugin_start() {

        new plugin_class();
    }

    add_action( 'plugins_loaded', 'plugin_start' );
} // sfârșitul class_exists

De asemenea, poți încărca prin mu_plugins_loaded pe instalări multisite, vezi codex pentru referința acțiunilor: http://codex.wordpress.org/Plugin_API/Action_Reference Aici poți vedea, cum să incluzi WP cu acest hook: http://adambrown.info/p/wp_hooks/hook/plugins_loaded?version=2.1&file=wp-settings.php Eu folosesc acest lucru foarte des și nu este atât de greu și timpuriu, mai bine decât un hard new class();

Descrierea plugin-ului tău ar trebui să detalieze în mod exact funcțiile acestuia. Există 10 plugin-uri pentru postări recomandate. Toate afișează postări recomandate, dar multe au caracteristici diferite. Ar trebui să fie ușor să compari plugin-ul tău cu plugin-uri similare prin citirea descrierii.

Ar trebui să eviți să te lauzi cât de simplu este plugin-ul tău, cu excepția cazului în care este într-adevăr foarte simplu. Ar trebui să incluzi link-uri utile în descriere, cum ar fi link-ul către setări.

Licențierea Plugin-urilor sub o Licență Compatibilă GPL

Plugin-urile și temele ar trebui să fie licențiate sub o licență compatibilă cu WordPress. Acest lucru le permite să fie redistribuite împreună cu WordPress ca un "program". O licență recomandată este GPL. Asigurați-vă că toate bibliotecile de cod incluse în plugin sunt compatibile cu aceeași licență.

(Acest lucru a fost o problemă și un subiect serios de dezbatere atât în trecut cât și în prezent.)

Minimizarea efectelor secundare ale surselor de date la distanță și serviciilor web

Un plugin ar trebui să memoreze în cache/protejeze serviciile web și/sau cererile XMLRPC/SOAP printr-un strat de caching/furnizor de date dacă le folosești, pentru a nu face ca cererile din frontend să aștepte răspunsul (lent) al serviciului web.

Aceasta include descărcarea fluxurilor RSS și a altor pagini. Proiectează plugin-urile tale astfel încât să solicite datele în fundal.

Un POSIBIL PAS este (luând ca exemplu postarea pe ping.fm): Creează o tabelă buffer, de exemplu: ping_fm_buffer_post( date, time, message, submitted_time, status )

1. De fiecare dată când dorești să trimiți o actualizare pe ping.fm, adaug-o în această tabelă.
2. Acum, trebuie să creăm un plugin pentru a gestiona aceste date. Acest plugin va rula prin crontab pentru a verifica fiecare actualizare care nu a fost încă trimisă
3. Deoarece avem această tabelă, putem de asemenea lista fiecare mesaj trimis pe ping.fm și verifica starea fiecărui post. Doar în cazul în care există o problemă pe partea ping.fm, o putem retrimite.

Folosește Standardele de Codare WordPress

http://codex.wordpress.org/WordPress_Coding_Standards

Știi cât de mult mai ușor este să actualizezi codul la care ai lucrat tu față de codul pe care l-a scris altcineva? Standardele de codare fac mai ușor pentru orice dezvoltator care lucrează la un proiect să înțeleagă rapid ce se întâmplă.

Știm că plugin-ul sau tema ta sunt ale tale, iar modul în care îți organizezi liniile și adaugi acoladele este o expresie a individualității tale. Fiecare indentare este o declarație atent gândită. Dar prin codul tău personalizat, contribui la WordPress, chiar dacă codul tău nu face parte din aplicația de bază. Standardele de codare ajută dezvoltatorii să înțeleagă mai repede codul tău.