Ajouter des tables personnalisées dans un thème ou une extension WordPress avec dbDelta()

Il arrive fréquemment qu'un thème ou une extension ait besoin de ses propres tables. La fonction dbDelta() permet de créer et de mettre à jour ces tables de façon intéressante et efficace.

Attention : il ne faut jamais modifier la structure des tables faisant partie de l'API de WordPress. Si vous le faites, vous risquez de perdre vos modifications lors de la prochaine mise à jour.

▼Publicité

L'idée de base de dbDelta() est la suivante :

  • Si la table demandée n'existe pas, elle est créée selon la structure proposée.
  • Si la table existe, sa structure est comparée avec la structure proposée :
    • Les nouveaux champs sont ajoutés. 
    • Les champs qui diffèrent dans leur type ou dans leur longueur sont ajustés. 
    • Si le nom d'un champ est modifié, un nouveau champ sera créé avec le nouveau nom. L'ancien champ demeurera inchangé. 
    • dbDelta() ne supprimera aucun champ d'une table existante.

La fonction dbDelta() ne fait pas partie de l'API WordPress. Elle est définie dans le fichier wp-admin/includes/upgrade.php. Il faut donc ajouter une instruction require_once() avant son utilisation :

Ex :

WordPress (PHP)

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

dbDelta(...);

À quel moment les tables personnalisées doivent-elles être créées ?

Le meilleur endroit pour créer les tables personnalisées est lors de l'activation du thème ou de l'extension. Le code sera donc placé dans une fonction que sera appelée à un des endroits suivants :

  • Si les tables sont utilisées par un thème, on utilisera le « hook » after_switch_theme dans le fichier functions.php du thème.

    Ex :

    WordPress (PHP)

    add_action( "after_switch_theme", "mon_prefixe_creer_tables" );

  • Si les tables sont utilisées par une extension, on utilisera la fonction register_activation_hook() dans la classe de l'extension. Dans l'exemple suivant, les tables sont créées dans la méthode creer_tables() et cette méthode est définie dans la classe Mon_Extension : 

    Ex :

    WordPress (PHP)

    register_activation_hook( __FILE__, array( 'Mon_Prefixe_Mon_Extension', 'creer_tables' ) );

Attention : lors du développement de votre thème, si vous créez des tables en utilisant le « hook » after_switch_theme, vous devrez, dans votre tableau de bord, activer un autre thème puis revenir à votre thème pour que la fonction de rappel soit exécutée.

Ce problème ne se posera pas lorsqu'un autre site utilisera votre thème : dès qu'il l'activera, le « hook » after_switch_theme entrera en action.

Définition de la structure de la table et utilisation de dbDelta()

La structure de la table doit être définie à l'aide d'une requête CREATE TABLE. Pour plus de commodité, la requête sera stockée dans une variable et cette variable sera passée en paramètre à la fonction dbDelta().

Lors de la définition de la requête SQL, il faut absolument respecter les règles suivantes :

  • Chaque champ doit être sur sa propre ligne.
  • Pour identifier la clé primaire, utiliser PRIMARY KEY. Il doit y avoir deux espaces entre PRIMARY KEY et le nom de la clé primaire.
  • Il ne faut utiliser aucun caractère spécial alentour du nom des champs .

    Ex : ne pas faire :

    MySQL

    `matable_description` varchar(50)

    mais bien :

    MySQL

    matable_description varchar(50)

Afin d'éviter les conflits avec les extensions ou avec l'API WordPress, il est important d'ajouter les précautions suivantes :

  • Le nom de la table utilisera le préfixe donné dans le fichier wp-config.php. Comme le nom de la nouvelle table n'existe pas dans l'API WordPress, on ne peut pas utiliser directement $wpdb->ma_nouvelle_table. Le nom de la table sera stocké dans une variable dont la valeur débutera par $wpdb->prefix suivi du reste du nom de la table.
  • Afin de rendre le nom de la table unique, on ajoutera, immédiatement après le préfixe, un mot relié au thème ou à l'extension qui nécessite cette table. Le nom complet sera du genre prefixe_montheme_ma_nouvelle_table ou prefixe_monextension_ma_nouvelle_table.
  • Pour éviter d'alourdir le code inutilement, le nom des champs ne sera pas précédé par le nom du thème ou de l'extension. Par exemple, un champ contenant une description pourra s'appeler simplement description. Si vous avez l'habitude d'inclure quelques caractères identifiant la table au début du nom de chaque champ, ne tenez pas compte du préfixe ni du nom du thème ou de l'extension dans le nom du champ. Par exemple, dans la table prefixe_montheme_ami, le champ de description pourrait s'appeler  simplement ami_description.

Ex :

WordPress (PHP)

function montheme_creer_tables() {

   global $wpdb;

   $nom_table = $wpdb->prefix . 'montheme_ma_nouvelle_table';

   $sql = "CREATE TABLE $nom_table (

      matable_id bigint(20) unsigned NOT NULL auto_increment,

      matable_description varchar(50) NOT NULL,

      matable_autrechamp int NULL,

      PRIMARY KEY  (matable_id)

   );";

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

   dbDelta( $sql );

}

Identifiants

Si vous allez voir la structure des tables de l'API WordPress, vous remarquerez que les identifiants sont tous de type bigint(20). Il serait sage d'employer ce même type pour les identifiants de vos tables personnalisées.

De plus, si une de vos tables contient une clé étrangère liée à un de ces identifiants, vous devrez prendre soin de lui donner à elle aussi le type bigint(20).

Ajout d'enregistrements

Si vous avez besoin d'ajouter des enregistrements dans la table, vous pouvez utiliser la fonction $wpdb->insert() après avoir appelé dbDelta(). 

Attention : tenez compte du fait qu'un thème ou une extension peut être activée et désactivée plusieurs fois...

Ex :

WordPress (PHP)

$wpdb->insert( $nom_table, array( 'matable_description' => 'blablabla', 'matable_autrechamp' => 1 ) );

Pour plus d'information

« Custom Database Tables: Creating the Table ». WP tuts. http://wp.tutsplus.com/tutorials/plugins/custom-database-tables-creating-the-table/

« Creating Tables with Plugins ». Codex WordPress. http://codex.wordpress.org/Creating_Tables_with_Plugins

« WordPress – Tips on Creating and Updating Tables with dbDeltaWordPress – Tips on Creating and Updating Tables with dbDelta ». WhyPad. http://www.whypad.com/posts/wordpress-create-updat-tables-with-dbdelta/930/

« Custom Fields ». Codex WordPress. http://codex.wordpress.org/Custom_Fields

« Chapitre 11. Types de colonnes ». MySQL. http://dev.mysql.com/doc/refman/5.0/fr/column-types.html

Merci de partager ! Share on FacebookTweet about this on TwitterShare on Google+Share on LinkedInPin on PinterestShare on StumbleUponEmail this to someone
Catégories

2 commentaires

    • Christiane Lagacé

      Bien contente que ça vous ait été utile.

      Si vous prévoyez faire du développement WordPress, revenez visiter mon site prochainement puisque je compte publier dans les semaines qui viennent une série d’articles sur la personnalisation du tableau de bord.

      Salutations !

      Christiane