A la découverte des sources....code-source de SPIP

Avant d’entamer notre voyage initiatique, une petite révision s’impose : comme beaucoup de fonctionnalités de SPIP, les codes offerts aux administrateurs/webmestes de SPIP sont directement issus de fonctions php, et c’est souvent la seule façon d’en trouver la documentation : lire le source.
Pas la peine d’en avoir peur, vous ne pouvez rien casser (tant que vous n’écrivez pas [1]) !

C’est l’avantage d’un produit libre, comme SPIP ou Linux : vous avez accès au source !
Et, meme sans connaitre PHP, vous allez vite en comprendre l’intéret...

Pour lire le source php (du texte dans une langue anglaise de programmation..), il suffit de décompresser une archive de SPIP ; point besoin d’outils spéciaux, éditeurs de programme ou autres, un explorateur suffit, à moins que vous ne préféreriez lire avec une interface Web :
 l’incontournable https://doc.spip.org et
 le browser sur la zone librement ou
 le nouveau core - selon les branches, c’est ici pour naviguer),
 et je n’oublierai pas les présentations améliorées disponible sur https://phpxref.free.fr/spip/nav.ht... malheureusement pas actualisée (1.9.2), ou chez https://codes-libres.org [2]
 enfin la solution intégrée https://code.spip.net/ (celle qu’il faudra utiliser désormais !).

Dans tous les cas vous trouverez aussi bien les sources du core que ceux des plugins [3] : cela peut souvent servir d’exemple !

A première vue, c’est (encore une fois) la zone : plus de 4000 fichiers disséminés dans plus de 500 répertoires ! ?
 première étape, vous devez connaitre la différence entre fichiers .HTML (présentation des squelettes de pages et formulaires), .CSS pour les feuilles de styles, et les sources .php (qui renferment les programmes composant spip.
 seconde étape, vous réviserez l’organisation des répertoires privés de la version de Spip que vous étudiez : consultez par exemple programmer.spip, la référence doc.spip.

 Les squelettes

Commençons par les squelettes du privé : habitués déjà à l’organisation des squelettes (et peut-etre à la structure Zpip-dist et ses conventions ), vous devriez retrouver assez vite les squelettes d’origine, dans les sous-répertoires de ./squelettes-dist et ceux de ./prive pour l’interface privée : nous ferons juste une référence particulière pour leurs sous-dossiers nommés ./prive/formulaires/ d’où nous pourrons regarder les contenus des-dits formulaires,
et d’autres détails pour personnaliser l’espace privé.

Du coté du code source .php, cela se passe essentiellement dans tous les sous-répertoires de ./ecrire, voire aussi dans < ./plugins-dist (ou pour les SPIP 2 dans ./extensions).

Comprendre le rangement et la dénomination des fichiers se fera peu-à-peu peut-être, sauf à identifier les tables natives de spip qui sont mises-à-jour, voir La structure de base de données de SPIP 3....

Maintenant, il faudrait savoir quoi chercher : le où sera donné par une recherche de fichiers contenant le mot cherché dans la branche de votre source SPIP.. votre explorateur de fichiers vous donnera vite les réponses si vous cherchez d’après un libellé.

 Les Chaines de textes

Encore une difficulté à franchir ; les chaines de langues, qui parsèment presque tous les squelettes privés ou publics de spip. Pour faciliter l’internationalisation du produit, tous les libellés sont pré-codés sous forme d’un mot balisé particulier <:mot_balisé:>, la traduction étant définie dans l’un des fichiers de /lang [4].

Donc vous devez rechercher le mot-balise correspondant au libellé que vous guignez -en principe, les même mots avec des soulignés- dans le jeu de fichiers de langues ecrire_fr.php, prive_fr.php et spip_fr.php du dossier dédié [5] .

Et maintenant, on peut commencer l’exploration, sachant qu’essentiellement le langage de spip s’articule autour :
 des tables et des boucles
 des balises
 des filtres

Les tables (ou objets ) sont le stockage des donnes sur lesquels portent les boucles : pour dépasser les explications du manuel des boucles, PhpMyAdmin est votre ami, en attendant la mise-à-jour de la structure de la base de données.

 Les balises

Les mots-réservés des #BALISES correspondent à des fonctions php qui doivent donc être définies une fois dans un fichier source : vous chercherez la suite de caractères function balise_, en principe plutot en minuscules.

Par exemple, en recherchant function balise_url_page, vous arriverez facilement à lire le fichier ./ecrire/balises/url.php, avec une ligne qui serait :

Pas très explicite ! Tout ce qu’on peut en dire, c’est que la fonction existe, (avec un suffixe _dist, mais nous le verrons plus loin ! Et cela pourrait meme vous paraitre en contradiction avec votre connaissance opérationnelle de la balise...
Heureusement, en regardant quelques lignes autour de celle-ci, vous avez la chance de découvrir des commentaires :

Ces lignes (conventionnellement affichées en vert-de-gris) précédées de deux slash marquent des commentaires, écrit par un programmeur ..... à destination de ses seuls lecteurs humains : vous .

Si les premières lignes ont plutot valeur historique (le php3 était utilisé au début de SPIP), vous saurez desormais utiliser #URL_PAGE sans argument, et sans surprise (pour ré-afficher la page : mais pour être sur de la recalculer, penser à rajouter un |parametre_url{var_mode,recalcul}

En dessous, nous pourrons découvrir que la balise reçoit d’une part un code (celui de la page fond à charger) et d’autres arguments... peut-etre accolés par le filtre |parametre_url

 Fonctions surchargeables

Encore un point d’information : connaissez vous la surcharge des fonctions (ou des méthodes en programmation objet) !
Une fonction -que ce soit en programmation ou en mathématiques- ne peut avoir qu’une seule définition ; mais si on veut modifier le traitement effectué par une fonction du core, il faut ré-écrire la fonction, avec le "meme nom", mais pas au meme endroit [6], et gérer la co-existence des deux definitions : impossible...sauf en programmation objet.

Mais si c’est possible avec Spip ; plus précisément un fonctionnement spécial est prévu pour permettre ce type de traitement. Toutes les fonctions de spip prévues pour etre surchargeables, sont suffixées par ce _dist (voir Programmer Spip, et la recherche d’accès aux fonctions (le traitement de charger_fonction suit une logique ordonnée pour offrir ce comportement.

 Les filtres

Justement, les filtres, que vous connaissez bien : même principe, vous rechercherez la suite de caractères donnant le nom du filtre [7], précédé du mot réservé function :
function xxx(
Cette fois-ci vous avez des chances de récupérer une chaine un peu plus riche.. en arguments !
Il faut savoir que, contrairement a SPIP qui utilise les accolades, php utilise les classiques parenthèses pour entoure la liste de paramètres ; l’accolade ouvrante marque le début du code exécutable...

Prenons par exemple le filtre couper (l’un des premiers que j’ai utilisé : voici sa documentation ) :

Le filtre |couper coupe un texte après un nombre de caractères paramétrable....
Le filtre coupe par défaut à 50 caractères, mais on peut spécifier une autre longueur en la passant comme paramètre au filtre, par exemple : [(#TEXTE|couper80)].

Sans surprise, vous trouverez dans le fichier /inc/texte.php :

Et vous ferez naturellement la correspondance avec les paramètres :
 le premier, $taille vient de la chaine qui précédait le filtre [8]
 le second $taille precise la taille à laquelle tronquer : comme il n’est pas obligatoire, php impose au développeur Spip de préciser une valeur par défaut !
 quant au troisième, vous reconnaissez les caractères de suite habituels.

Comme un filtre de Spip n’est qu’une fonction php avec un premier argument caractères, implicite dans la syntaxe, vous risquez eventuellement de ne pas trouver dans le code de spip, un filtre du nom d’une fonction php, mais aucun exemple ne vient à l’esprit : si, |strlen pour afficher la seule longueur d’un texte.

 Les Critères

Toujours le meme principe : nous recherchons maintenant les fonctions commencant par ce nom, soit function critere_, que nous trouverons essentiellement dans <./ecrire/public/criteres.php.

Mais la syntaxe utilisée faisant appel à l’arbre syntaxique du Compilateur SPIP....

 Et les Bases de données

C’est encore une fois l’examen du source qui va nous piloter : mais il vous faut prendre connaissance d’une double interface, qui permet la grande supériorité de SPIP en gestionnaire multi-base ; on utilisera en developpement un jeu de fonctions [9]génériques sql_ expliquée sur Spip-DOC, SPIP se chargeant de gérer la correspondance vers la bonne implémentation en fonction du type de SGBD, serveur de gestion de base de données utilisé dans la connection...

Vous relirez activement les commentaires des fonctions-clés de SPIP, maintenant que vous voyez comment y plonger.