Creare e aggiornare tabelle con la funzione dbDelta

Vediamo adesso come immagazzinare i dati di un plugins WordPress come opera la funzione dbDelta. Diciamo che questo è il metodo più generale per farlo. Ossia per creare tabelle su Mysql o Maria DB in un contesto WP.  I passi che dovremo fare sono i seguenti

Creare una funzione PHP che crei le tabelle del database Mysql / Maria.

Creare una funzione di aggiornamento se una nuova versione del plugins necessità di una struttura del database differente.
Creare tabelle nel Database.
Per il resto della lezione assumeremo che la funzione sia jal_install e che il database su cui opereremo sia Mysql e MariaDB.

Inoltre lasceremo il prefisso inalterato dentro il table wp_config.php quindi il metodo prefix conterrà sempre il valore standard wp_

Con queste premesse andiamo a incominciare

Andiamo a creare la funzione per la creazione delle tabelle che è

function jal_install () {
 global $wpdb;

$table_name = $wpdb->prefix . "liveshoutbox"; 
}

A questo punto ricorreremo ad una funzione particolare che si chiama dbDelta

La funzione per modificare database dbDelta

Questa funzione è molto particolare ed è stata introdotta proprio allo scopo di permettere di interagire con il database MySql e Mariadb. Questa particolare funzione crea una sorta di accordo di matching fra le tabelle desiderate dall’utente e quelle già create dal WordPress.

Il suo utilizzo è alquanto semplice e lo possiamo trarre direttamente dal sito di wordpress che mostra

global $wpdb;

$charset_collate = $wpdb->get_charset_collate();

$sql = "CREATE TABLE $table_name (
 id mediumint(9) NOT NULL AUTO_INCREMENT,
 time datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
 name tinytext NOT NULL,
 text text NOT NULL,
 url varchar(55) DEFAULT '' NOT NULL,
 PRIMARY KEY (id)
) $charset_collate;";

require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
dbDelta( $sql );

Ossia come potete vedere carichiamo la variabile sql per fargli creare una tabella che avrà una primary key id etc. etc.

Richiama il file file upgrade.php per fare l’aggiornamento con il database e dopo la funzione dbDelta che appunto fa il matching fra richiesta dell’utente e il database creato dal WP.

Questo detto molto in generale, ma veniamo nello specifico e vediamo quali parametri tiene in considerazione la funzione.

• Per ogni campo si deve utilizzare una riga dell’istruzione SQL.
• È necessario disporre di due spazi tra le parole chiave primaria e la definizione della chiave primaria.
• È necessario utilizzare la parola chiave, piuttosto che un sinonimo di INDEX e si deve includere almeno una chiave.
• il termine KEY deve essere seguito da un singolo spazio, poi il nome, uno spazio e parentesi aperta con il nome del campo poi una parentesi chiusa.
• Non si deve utilizzare apostrofi o backticks intorno ai nomi dei campi.
• I Tipi di campo devono essere tutti in minuscolo.
• Le parole chiave SQL, come CREATE TABLE e UPDATE, deve essere maiuscolo.
• È necessario specificare la lunghezza di tutti i campi che accettano un parametro di lunghezza. int (numero) ,varchar(numero) , etc. etc.

Se controllate il codice PHP della query SQL scritto sopra potete vedere che tutti questi parametri sono stati rispettati . In questo caso non avremmo quindi nemmeno avuto bisogno della funzione dbDelta. Che in ogni modo è altamente consigliata utilizzare.

Vediamo adesso come aggiungere i dati alla vostra tabella creata.

Premetto che nel fare questa particolare guida su DB e WP ho molto seguito quella in inglese su codex wordpress da cui mi sono discostato pochissimo)

In questo caso il codice da inserire sarà

$welcome_name = 'Ciao Noirsolutions';
$welcome_text = 'Complimenti, la tua installazione è completata!';

$table_name = $wpdb->prefix . 'liveshoutbox';

$wpdb->insert( 
 $table_name, 
 array( 
 'time' => current_time( 'mysql' ), 
 'name' => $welcome_name, 
 'text' => $welcome_text, 
 ) 
);

Come potete vedere il metodo è abbastanza lineare. Unico dato da sottolineare è che per fare l’inserimento nel DB abbiamo utilizzato il medodo insert della classe wpdb.
Wordpress suggerisce anche di immettere un record con la versione in modo tale da rendervi la vita più agevole quando andrete a fare l’aggiornamento. In questo caso è semplicemente

add_option( "jal_db_version", "1.0" );

A questo punto la funzione è definita e inizializzata. Il successivo passo che vi richiederà WordPress è che venga registrata in modo da poter essere richiamata da WP dopo che il plugins nel quale il codice della funzione risiede viene attivato da un utente avente il rango di Amministratore.

Nel caso che la funzione abbia un url relativo del tipo

wp-content/plugins/plugindir/pluginfile.php

ossia del tipo consigliato da WP basterà utilizzare il codice

register_activation_hook( __FILE__, 'jal_install' );
register_activation_hook( __FILE__, 'jal_install_data' );

Il primo rigo per la creazione delle tabelle su DB il secondo per l’inizializzazione.
Ricordatevi sempre che tali tabelle devono essere anche inizializzate.

Aggiungere e Aggiornare funzione database

Durante il periodo di vita di un plugins è verosimile che avrete bisogno di modificare la struttura del database o aggiornare la versione.

Il modo piè semplice per fare questo è aggiungere del codice alla funzione jal_install .

Per esempio supponiamo di avere un plugins e che nel database è registrato con la version 1.0 e vogliamo fare un aggiornamento alla versione 1.1 e nella nuova versione vogliamo portare il campo url da varchar 55 che era prima a varchar 100 . In questo caso nella nostra funzione jal_install dovremmo aggiungere il seguente codice

<?php

global $wpdb;
$installed_ver = get_option( "jal_db_version" );

if ( $installed_ver != $jal_db_version ) {

$table_name = $wpdb->prefix . 'liveshoutbox';

$sql = "CREATE TABLE $table_name (
 id mediumint(9) NOT NULL AUTO_INCREMENT,
 time datetime DEFAULT '0000-00-00 00:00:00' NOT NULL,
 name tinytext NOT NULL,
 text text NOT NULL,
 url varchar(100) DEFAULT '' NOT NULL,
 PRIMARY KEY (id)
 );";

require_once( ABSPATH . 'wp-admin/includes/upgrade.php' );
 dbDelta( $sql );

update_option( "jal_db_version", $jal_db_version );
}

che come potete vedere è molto semplice carica la versione installata da db sulla variabile installed_ver e nel caso non sia la stessa di $jal_db_version che caricheremo con version 1.1 farà l’aggiornamento voluto.
dobbiamo fare però ora un passo successivo. In quano la fuzione di attivazione del database che abbiamo già visto ossia register_activation_hook non viene chiamata quando un plugin viene aggiornato. Quindi se non facessimo nulla rimarrebbe inalterata la versione precedente del plugin. Allora bisogna ricorrere ad un altro “gangio” che controlli se la versione è quella aggiornata nel seguente modo.

function myplugin_update_db_check() {
 global $jal_db_version;
 if ( get_site_option( 'jal_db_version' ) != $jal_db_version ) {
 jal_install();
 }
}
add_action( 'plugins_loaded', 'myplugin_update_db_check' );

E per questa lezione su come creare database è veramente tutto