Carnet Wiki

A la découverte des sources.... de SPIP

Version 14 — Juin 2012 YannX

SPIP est un logiciel libre : cela veut dire en particulier que les sources sont ouvertes, modifiables certes, mais déjà à lire  !

Pour les core-dev, qui connaissent par coeur tant php que ces sources, c’est du biberon !
Et certains vous assommeront, à grand renfort de RTFM [1]..... sauf que le manuel de Spip ne suit pas toujours.
Ou ils vous prieront d’écrire la doc.... « à partir de quoi ? » vous enteterez-vous ? et « Read The F...Source Code »

Et là, il faut oser : un jour, j’ai pas eu le choix ; alors, je pense à tous ceux qui n’ont pas ( -pas encore- ;) franchi le pas : c’est pas si difficile, et sans danger !

Et j’ai commencé à écrire ce que j’aurais bien aimé pouvoir lire en accompagnement il y a quelque temps....

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 [2]) !

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 un langage 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 [-> org" class="spip_url spip_out auto" rel="nofollow external">http://doc.spip.org] org et
-  la zone librement ou - le nouveau core - selon les branches, c’est ici pour naviguer),
-  et je n’oublierai pas la présentation améliorée disponible sur [->http://codes-libres.org] malheureusement pas toujours actualisée

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 sans oublier ./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....

Maintenant, il faudrait savoir quoi chercher : le 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 <code>< :mot_balisé:>&lt;/code code><:mot_balisé&lt;:</code >}}, la traduction étant définie dans l'un des fichiers de &lt;code>/lang [aux  (…)" id="nh4">4]. code>/lang</code > .

Donc vous devez rechercher le mot-balise correspondant au libellé que vous guignez -en principe, les meme 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 :

function balise_URL_PAGE_dist($p) {

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 :

//
// #URL_PAGE{backend} -> backend.php3 ou ?page=backend selon les cas
// Pour les pages qui commencent par "spip_", il faut eventuellement
// aller chercher spip_action.php?action=xxxx
// Sans argument, #URL_PAGE retourne l'URL courante.
// #URL_PAGE* retourne l'URL sans convertir les & en &
// http://doc.spip.org/@balise_URL_PAGE_dist
function balise_URL_PAGE_dist($p) {


$code = interprete_argument_balise(1,$p);
	$args = interprete_argument_balise(2,$p);
       .....

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 ) :

<blockquote class="spip">

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)].

</blockquote>

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

// http://doc.spip.org/@couper
function couper($texte, $taille=50, $suite = ' (...)') {
	if (!($length=strlen($texte)) OR $taille <= ) return '';  
......

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....

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

Dans vos explorations de SPIP, vous decouvrirez encore que certains balises ou fonctions ne sont pas définies (mettant à mal notre technique de recherche exposée plus haut) mais reconstruites par concaténations de chaines de caractères....
A un autre épisode, à vous !