**SPIP**
# Article proposé
L’article "**Le fichier _administrations des plugins**
(https://www.spip.net/ecrire/?exec=article&id_article=6497)" est proposé
à la publication depuis le lundi 4 mars 2019.
* * *
## Le fichier _administrations des plugins
lundi 4 mars 2019 , par [JLuc](.././?page=auteur&id_auteur=55&)
Pour leur fonctionnement propre, certains plugins nécessitent de nouveaux
champs dans les tables SPIP, ou de nouvelles tables, ou des enregistrements
particuliers dans celles-ci. Il est fréquent, par exemple, qu’un plugin
enregistre sa configuration dans la table `spip_meta`. C’est le rôle de
la procédure d’installation du plugin que de faire ces modifications.
Par ailleurs, il est fréquent que ces besoins évoluent lors du
développement du plugin. De nouveaux champs ou de nouvelles tables sont
utilisées. Ou parfois, le format de certaines données change et
nécessite une conversion de l’ancienne version vers la nouvelle. Lors
d’une montée de version du plugin, c’est le rôle de la procédure de
mise à jour (upgrade) de faire ces changement.
Inversement, lorsqu’on désinstalle un plugin, il faut faire le ménage,
nettoyer les valeurs, les champs, les tables et autres modifications
introduites par le plugin.
Le fichier `prefixe_administrations.php` est le réceptacle des fonctions
appelées à chacune de ces étapes pour réaliser ces diverses
manipulations, par exemple chaque fois que vous installez, mettez à jour
ou désinstallez un plugin avec SVP.
*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 schema de données par un plugin peuvent porter sur :
- l’ajout de champs à des tables SPIP
- la création de nouveaux objets editoriaux
- 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.
Note : Dans SPIP2, la version du schéma était décrite par la
`<version_base>` dans `plugin.xml`.
Pour faciliter les mises à jour, il est conseillé que ce schéma soit un
entier, en prenant le numéro de dépôt ou la date sous forme
`AAAAMMJJHHMM` : cela permet de retrouver facilement la raison d’un
changement. Toutefois d’autres formes sont possibles et en pratique, ce
schéma est souvent de la forme `x.y.z` où `x`, `y` et `z` sont des
entiers.
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`, son 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 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.
- Il existait auparavant une fonction historique `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 deux fonctions ci-dessus.
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
(http://www.php.net/array)
(
)
;
$maj
[
'create'
]
=
array
(http://www.php.net/array)
(
array
(http://www.php.net/array)
(
'maj_tables'
,
array
(http://www.php.net/array)
(
'spip_versions'
,
'spip_versions_fragments'
)
)
,
array
(http://www.php.net/array)
(
'revisions_update_meta'
)
,
)
;
$maj
[
'1.1.0'
]
=
array
(http://www.php.net/array)
(
array
(http://www.php.net/array)
(
'sql_alter'
,
'TABLE spip_versions CHANGE id_article id_objet bigint(21) DEFAULT 0
NOT NULL'
)
,
array
(http://www.php.net/array)
(
'sql_updateq'
,
'spip_versions'
,
array
(http://www.php.net/array)
(
'objet'
=>
'article'
)
,
"objet=''"
)
,
...
)
;
$maj
[
'1.1.2'
]
=
array
(http://www.php.net/array)
(
array
(http://www.php.net/array)
(
'revisions_update_meta'
)
,
array
(http://www.php.net/array)
(
'sql_updateq'
,
'spip_versions_fragments'
,
array
(http://www.php.net/array)
(
'objet'
=>
'article'
)
,
"objet=''"
)
,
)
;
$maj
[
'1.1.3'
]
=
array
(http://www.php.net/array)
(
array
(http://www.php.net/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
## `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()`
(https://programmer.spip.net/sql_alter).
<!-- -->
* Pour mettre à jour certaines valeurs, on utilisera des appels à
`sql_updateq()` (https://programmer.spip.net/sql_updateq,593).
<!-- -->
* Pour les métas, on peut utiliser `ecrire_config()`
(https://code.spip.net/autodoc/tree/ecrire/inc/config.php.html#function_ecrire_config)
pour mettre à jour des paramètres de configuration du plugin.
**Pour la désinstallation**
- sql\_drop\_table
(https://code.spip.net/autodoc/tree/ecrire/base/abstract_sql.php.html#function_sql_drop_table)
- effacer\_config
(https://code.spip.net/autodoc/tree/ecrire/inc/config.php.html#function_effacer_config)
ou effacer\_meta
(https://code.spip.net/autodoc/tree/ecrire/inc/meta.php.html#function_effacer_meta)
— Envoyé par SPIP (https://www.spip.net/)
