[ kalizi.dev ]

Come iniziare lo sviluppo di plugin WordPress con Docker: Parte 1, Docker e pannello Admin

Photo by Launchpresso on Unsplash

“Beautiful designs, powerful features, and the freedom to build anything you want. WordPress is both free and priceless at the same time.” ~ Wordpress.org

Se lavori nel web, hai sentito parlare di WordPress. È un must! Con WordPress puoi letteralmente costruire qualsiasi cosa.

Dal punto di vista di un nuovo utente, WordPress è un bel CMS: installi un tema, lo configuri, installi i plugin di cui hai bisogno, puoi persino sistemare qualche aspetto SEO usando un plugin apposito.

Dal punto di vista di uno sviluppatore, è diverso. WordPress è come un framework. Pensaci un attimo: con WordPress hai:

  • routing: puoi scrivere i tuoi URL personalizzati come vuoi.
  • interfacciamento con il database: hai tantissime funzioni con feature utili come i prepared statement e la sanitizzazione dei parametri.
  • templating: puoi aggiungere il tuo template, estendere quello di un plugin o addirittura frammentare la view e definire ogni sotto-view separatamente.
  • gestione dei media: può gestire immagini, audio e video senza che tu debba scrivere codice.
  • gestione di autenticazione/permessi: la gestione dei ruoli è modificabile come preferisci.
  • pannello di amministrazione: hai una bella dashboard che puoi estendere. Puoi aggiungere menu, pagine e impostazioni senza dover ricostruire nulla.

Non è un framework, ma gli somiglia davvero molto. Con questa prospettiva, iniziamo a progettare il nostro plugin!

Un ambiente di sviluppo usa e getta per WordPress 🔧

Se sviluppi già "roba WordPress", probabilmente hai già un ambiente di sviluppo con cui ti trovi bene e, se non vuoi cambiare, puoi saltare questa parte e passare al generatore, ma se vuoi avere un altro punto di vista, eccolo qui. Se usi una strategia diversa perché la ritieni più semplice o più efficace, fammelo sapere nei commenti: è sempre apprezzato leggere i commenti di altri sviluppatori!

La community di Docker mantiene un'immagine ufficiale di WordPress con:

  • Apache as a web server
  • PHP-FPM as process manager
  • WP-CLI come helper da riga di comando (non conosci WP-CLI? Scoprilo qui)
  • MySQL come DBMS
  • PHPMyAdmin come utility di esplorazione dei database

Ecco un fatto interessante: queste immagini sono ready-to-go, non è necessario sapere per forza come funziona Docker per usarlo sulla tua macchina locale, ti basta seguire i passaggi, avviare le immagini, sviluppare la tua roba WordPress e infine pulire tutto.

Configurare l'ambiente con Docker è davvero semplice:

  • L'immagine ufficiale Docker è disponibile qui su Github, ti basta clonarla con git clone https://github.com/nezhar/wordpress-docker-compose.git.
  • Entra nella cartella clonata e lascia che Docker faccia il resto con docker-compose up -d.

Questo farà sì che Docker scarichi le immagini da DockerHub e assembli il tuo ambiente. Se guardi il contenuto della cartella, dovresti vedere un file .env:

IP=127.0.0.1
DB_ROOT_PASSWORD=password
DB_NAME=wordpress

Questo file dovrebbe aiutarti a sistemare quei 3 parametri, prima della build, per cambiare il comportamento predefinito delle immagini. Una volta che Docker ha finito, ti basta aprire localhost e il tuo WordPress è pronto per la configurazione!

Installazione di WordPress con Docker

I tuoi file WordPress si trovano nella cartella wp-app!

Generatore di WordPress Plugin Boilerplate ✏️

I plugin WordPress possono essere strutturati come preferisci, puoi semplicemente buttarci dentro i file, senza una struttura specifica, e se hai seguito le 2/3 regole scritte nel Codex, il tuo plugin funzionerà. Se hai già la tua struttura, benissimo, vai con quella; se vuoi provare una nuova struttura o lo stai facendo per la prima volta, un boilerplate può essere un buon punto di partenza.

Ho provato diversi boilerplate e il mio preferito in assoluto è WPPB(WordPress Plugin Boilerplate).

wppb.me: generatore di boilerplate

Per essere davvero innovativi, costruiamo un Hello World.

wppb.me

Dopo aver cliccato "Build Plugin", otterrai lo zip del boilerplate del tuo plugin nella cartella dei download! Dopo averlo estratto, vedrai un sacco di file. Sono organizzati in 3 comode cartelle:

  • admin: dove sta la roba relativa all'amministrazione.
  • public: dove sta la roba relativa alla parte pubblica.
  • includes: dove avviene la magia.

Adotteremo l'approccio "usa prima, impara dopo", il che significa che impareremo facendo e poi approfondiremo esaminando l'esatto flusso di funzionamento di questo boilerplate.

Installare il plugin nel tuo ambiente locale

Come detto prima, il tuo ambiente WordPress locale si trova nella cartella wp-app; per sviluppare il tuo plugin più velocemente, copia la cartella del plugin dentro wp-app/wp-content/plugins e vai su http://localhost/wp-admin/plugins.

Plugin installati

Il plugin è pronto per essere attivato, e la parte bella è che puoi attivarlo, svilupparlo, aggiornare la pagina e vedere ciò che hai appena fatto in tempo reale. Attivalo e inizia il processo di sviluppo!

Hello world dal pannello Admin

Per iniziare a sviluppare il pannello di amministrazione dovresti partire dalla classe Admin in admin/class-kalizi-hello-world-admin.php. Nella cartella partials ci saranno le tue view per ogni pagina. Per iniziare a registrare una pagina, crea un metodo nella classe admin dove starà la logica della tua pagina e includi lì la view, semplicissimo.

public function adminHello() {
    include 'partials/kalizi-hello-world-admin-display.php';
}

Se apri la pagina inclusa, ci saranno un sacco di commenti, puoi mettere il tuo codice HTML dopo l'apertura del tag PHP, tipo

<h1>Hello world</h1>

Ma con questo non è ancora fatto nulla, devi comunicare a WordPress l'esistenza della tua pagina tramite l'hook admin_menu. Per registrare un hook, dovresti dare un'occhiata a includes/class-kalizi-hello-world.php: lì troverai un metodo chiamato define_admin_hooks dove viene istanziata la classe di amministrazione e due action per accodare gli script. Per registrare le pagine di menu dobbiamo aggiungere un altro metodo che gestisca l'hook nella classe admin.

public function register_menu() { }

Poi in define_admin_hooks basta collegarlo all'hook:

$this->loader->add_action( 'admin_menu', $plugin_admin, 'register_menu' );

In register_menu puoi registrare la pagina di amministrazione usando add_menu_page:

public function register_menu() {
  add_menu_page(
   'Hello Page Title',
   'Hello Menu',
   'manage_options',
   'hello_from_kalizi',
   [ &$this, 'adminHello' ]
  );
 }

I suoi parametri, in ordine, sono:

  • titolo della pagina.
  • titolo del menu.
  • capability: ti permette di controllare chi avrà accesso a cosa, manage_options sono i permessi per un utente che può accedere alle schermate di amministrazione (controllali qui).
  • slug del menu.
  • funzione callable: seguirà la modalità call_user_func di PHP, per invocare un metodo dovresti usare la sintassi [$className, $methodName].
  • URL dell'icona: è opzionale, puoi aggiungere un'icona ai tuoi file e ottenerne l'URL tramite plugin_dir_url(__FILE__).’/path/to/image’.
  • posizione: i menu di WordPress seguono un ordinamento indicizzato, per controllare l'ordine dei tuoi menu dovresti usare print_r($GLOBALS['menu') come nella documentazione di Administration Page.

Il menu registrato

Una volta che lo cliccherai, verrà effettuata la chiamata ad adminHello che includerà la view.

Hello world

🔥 È l'ora del battesimo del fuoco, ragazzo 🔥

Database 💾

Se stai costruendo un plugin, a meno che tu non stia facendo qualcosa di statico, ti serviranno delle tabelle. Per configurare le tue tabelle, dai un'occhiata a includes/class-kalizi-hello-world-activator.php. Lì dentro c'è un metodo chiamato activate dove dovresti mettere la logica di inizializzazione del DB.

Per eseguire istruzioni CREATE, devi prima avvisare WordPress, in questo modo:

global $wpdb;
require_once(ABSPATH . 'wp-admin/includes/upgrade.php');

La prima riga richiama $wpdb, la classe di astrazione per l'accesso al database di WordPress.

La seconda riga richiede upgrade.php per usare dbDelta, una funzione per modificare il database con SQL. Quindi, per eseguire un'istruzione CREATE, dovresti:

$query = "
 CREATE TABLE IF NOT EXISTS {$wpdb->prefix}hello_from_the_database (
  id BIGINT(20) NOT NULL AUTO_INCREMENT,
  hello_from VARCHAR(20) NOT NULL,
  hello_message LONGTEXT NOT NULL
  PRIMARY KEY(id)
 ) {$wpdb->get_charset_collate()};
";
dbDelta($query);
if (! empty($wpdb->last_error)) {
 // What you gonna do if this fails?
}

Se sei già dentro WordPress, dovresti sapere che tutte le tabelle di WordPress hanno un prefisso, quindi devi aggiungere anche quello con $wpdb->prefix e mantenere il collate di WP.

Per eseguire una query, devi invocare di nuovo $wpdb, puoi trovare maggiori informazioni nella documentazione di WordPress su WPDB.

Per l'amministrazione, è tutto per oggi!

Photo by Stephen Phillips - Hostreviews.co.uk on Unsplash

Una volta che conosci le basi per lavorare sulla parte admin, puoi fare tutto ciò che immagini, la documentazione di WordPress ha un sacco di action che puoi usare delegando i tuoi metodi.

Se hai qualche domanda su questa parte, vuoi saperne di più su wp-admin o hai una domanda sullo sviluppo di plugin, lascia pure un commento qui sotto. 💬

Resta sintonizzato per i prossimi articoli di questa serie: approfondiremo il boilerplate, parleremo di come fare qualcosa sulla parte pubblica, di come usare ajax o il tuo framework o le tue librerie JS preferite, e di molto altro ancora! Fammi sapere se vuoi che mi concentri su qualche aspetto dello sviluppo dei plugin WP e buona giornata! ☕️