Le fichier _administrations des plugins

Le fichier _administrations d’un plugin sert à décrire les actions à effectuer lors de l’installation, de la mise à jour ou de la désinstallation d’un plugin.

Dans ce qui suit, ’prefixe’ est le prefixe du plugin concerné, et doit être remplacé dans votre code par le véritable préfixe de votre plugin.

Version du ’schéma’ des données

Les modifications du schéma de données par un plugin peuvent porter sur :

  • l’ajout de champs à des tables SPIP
  • la création de nouveaux objets éditoriaux
  • l’enregistrement de paramétrages dans les métas.
  • d’autres opérations, telle que la création d’un fichier annexe ou l’envoi d’un mail.

Dans le fichier paquet.xml décrivant un plugin, l’attribut schema sert à indiquer la version courante du schéma de données utilisé par le plugin : cette valeur schema doit être incrémentée à chaque modification des structures du plugin.

Pour faciliter les mises à jour, il est conseillé que ce schéma prenne la forme x.y.z (versionnement sémantique) ou un entier incrémenté à chaque nouvelle version du schéma (le format AAAAMMJJHHMM est désormais déconseillé).

Si cet attribut est spécifié dans le fichier XML, il est indispensable de créer un fichier prefixe_du_plugin_administrations.php pour définir les traitement à appliquer aux tables de données, lors des procédures d’installation, de mise à jour et de désinstallation du schéma de base de données du plugin.

Pour chaque plugin de préfixe prefixe, le fichier prefixe_administrations.php est lu automatiquement lors de la consultation de la page d’administration des plugins, lorsqu’il y a un changement de version de schéma, ou lors d’une désinstallation.

Si elles sont définies dans ce fichier, les deux fonctions de mise à jour sont alors exécutées :

  • prefixe_upgrade() : upgrade à une nouvelle version. Reçoit 2 arguments : $nom_meta_base_version (la version de schéma du plugin actuellement installé) et $version_cible (la version du schéma vers laquelle on fait l’upgrade).
  • prefixe_vider_table() : pour désinstaller le plugin. Un seul argument : la version du schéma.

Dans chacune de ces fonctions, on fait ce qu’il faut pour faire la mise à jour ou la désinstallation, en fonction des versions reçues en argument.

prefixe_upgrade()

À la fin de prefixe_upgrade(), on appelle toujours maj_plugin($nom_meta_base_version, $version_cible, $maj);.
Le tableau $maj reçu en troisième argument contient la liste des actions à faire pour chaque montée de version en base, et donc avant d’appeler maj_plugin, il faut construire ce tableau, élément par élément.

Chaque élément de $maj est une liste (= un tableau) d’actions. Chaque action est à son tour un tableau contenant le nom de la fonction à appeler , suivi de ses arguments.

Le premier élément de $maj a souvent pour index : 'create' et contient un appel à maj_table() avec la liste des tables à créer. Le create peut aussi contenir d’autres actions.
L’étape 'create' est utilisée lors d’une installation initiale seulement. Elle doit toujours générer l’installation complète et à jour du plugin. S’il n’y a pas d’étape 'create', alors toutes les étapes de $maj sont exécutées à la suite les unes des autres.

Pour les autres étapes décrites par $maj : les éléments suivants de $maj ont pour index le numéro de schéma à partir duquel il faut faire cette action lors d’un upgrade. Lors d’une mise à jour, les index sont comparés à la version existante et celles nécessaires sont utilisées pour cette mises à jour.

Exemple (extraits du plugin révisions, livré avec SPIP) :

$maj = array();
$maj['create'] = array(
    array('maj_tables', array('spip_versions', 'spip_versions_fragments')),
    array('revisions_update_meta'),
);
$maj['1.1.0'] = array(
    array('sql_alter', 'TABLE spip_versions CHANGE id_article id_objet bigint(21) DEFAULT 0 NOT NULL'),
    array('sql_updateq', 'spip_versions', array('objet' => 'article'), "objet=''"),
    ...           
   );
$maj['1.1.2'] = array(
    array('revisions_update_meta'),
    array('sql_updateq', 'spip_versions_fragments', array('objet' => 'article'), "objet=''"),
);
$maj['1.1.3'] = array(
    array('sql_alter', 'TABLE spip_versions DROP KEY id_objet'),
);

include_spip('base/upgrade');
maj_plugin($nom_meta_base_version, $version_cible, $maj);
}

Dans cet exemple, la fonction revisions_update_meta() est propre au plugin revision. Elle est définie un peu plus loin dans le fichier revision_administrations.php et se charge d’installer les configuration initiale du plugin, via la fonction ecrire_config() de SPIP.

Si par exemple, si la version actuelle du plugin est la version 1.1.0, alors la mise à jour vers la 1.1.2 va d’abord être jouée, puis vers la 1.1.3, etc

Autre exemple : initialiser les données d’une table

À son installation, le plugin opquast crée une table et l’initialise. Pour cela, la fonction d’upgrade demande d’appeler une fonction populate_opquast_criteres définie spécialement à cet effet :

function opquast_upgrade($nom_meta_base_version, $version_cible) {
	$maj = array();

	$maj['create'] = array(
		array(
			'maj_tables',
			array(
				'spip_opquast_criteres',
				'spip_opquast_criteres_liens',
				'spip_opquast_tags',
				'spip_opquast_themes',
				'spip_opquast_etapes',
			),
		),
		array('populate_opquast_criteres'),
	);
...

La fonction populate_opquast_criteres est définie un peu plus loin : elle lit 2 fichiers json et insère dans la table, avec des appels à sql_insertq, les lots de données lues dans ces fichiers.

prefixe_vider_table()

prefixe_vider_table() doit permettre, lors d’une désinstallation, la destruction des tables créées et toutes les actions de nettoyage (notamment des configurations) avec perte des informations stockées. Elle reçoit un argument : $nom_meta_base_version, qui correspond au préfixe du plugin.

Exemple pour le plugin des statistiques (également livré avec SPIP) :

function stats_vider_tables($nom_meta_base_version) {
    sql_drop_table("spip_visites");
    sql_drop_table("spip_visites_articles");
    sql_drop_table("spip_referers");
    sql_drop_table("spip_referers_articles");

    effacer_meta("activer_statistiques");
    effacer_meta("activer_captures_referers");

    effacer_meta($nom_meta_base_version);
}

Fonctions utiles

On peut appeler toute fonction php dans les étapes de mise à jour. En pratique, les fonctions suivantes seront souvent utiles :

Pour la mise à jour

  • Pour ajouter un champ dans une table, on utilisera sql_alter().
  • Pour mettre à jour certaines valeurs, on utilisera des appels à sql_updateq().
  • Pour les métas, on peut utiliser ecrire_config() pour mettre à jour des paramètres de configuration du plugin.

Pour la désinstallation

Historique

  • Il existait auparavant une fonction prefixe_install() qui gérait à la fois l’installation, la mise à jour et la désinstallation du plugin ; mais cette fonctionnalité est désormais dépréciée et il est conseillé d’utiliser les fonctions décrites ci-dessus.
  • SPIP < 3.0 : la version du schéma était décrite par la <version_base> dans plugin.xml.

Auteur JLuc Publié le : Mis à jour : 03/03/22