Organització de les fonts
A partir de la versió 1.9, és possible modificar el comportament d’SPIP
sense alterar les seves fonts, gràcies a la rutes d’accés definides per la constant SPIP_PATH.
Tota extensió d’SPIP ha d’operar d’aquesta manera per tal que un test d’integració sigui desconnectable per simple redefinició del camí d’accés, suposant que la distribució d’SPIP sigui només de lectura.
Si esteu convençuts que un cert comportament no es pot aconseguir d’aquesta manera, escriviu a la llista de discussió spip-dev.
Les col·laboracions a SPIP cal descriure-les en un article a Spip-Contrib i el seu contingut es pot posar o bé com a adjunt a aquest article, o bé, i molt millor, a spip-zone que proveeix un servidor Subversion guiat per Trac.
D’aquesta manera, per ampliar SPIP cal comprendre bé l’organització d’aquests directoris i el paper dels seus arxius. És la finalitat d’aquest article, però també haurem de llegir amb profit l’article que anunciava SPIP 1.9 que és qui l’ha inaugurat.
L’arrel d’una distribució d’SPIP comporta essencialment:
- un arxiu
spip.php, àlies
index.php, gestionant la compatibilitat amb les versions antigues, carregant el fitxer d’inicialització ecrire/inc_version.php
i passant immediatament la mà al script principal
ecrire/public.php;
- un directori
ecrire
on hi ha exclusivament arxius interpretables pel servidor (PHP i SQL);
- un o diversos (segons les versions) directoris que tenen arxius interpretables pel cantó del client (HTML, Javascript, fulls d’estil, imatges de diferents formats) així com els patrons de disseny anomenats esquelets. Aquests esquelets són interpretats per dues bandes: es tracta d’arxius compostos d’un format MIME completat amb algunes directrius SPIP, directius tractades a nivell de servidor per tal d’enviar al client un text purament MIME (la major part de les vegades HTML, però també RSS, SVG, ICS etc).
- quatre directoris buits en el moment de la instal·lació, que contindran les dades, temporals o permanents, necessàries per la vida del lloc.
Funcións dels directorisi prive i squelettes-dist i dels seus subdirectoris
Contenen els arxius que determinen la presentació d’SPIP, per l’espai privat i l’espai públic respectivament.
Abans d’SPIP 2.0, aquests dos arxius eren un de sol anomenat dist. Contenen molts subdirectoris dels que veurem aquí les especificacions:
| directori | funció |
|---|---|
/ |
conté els esquelets. El seu nom acaba amb
.html per raons històriques però això no prejutja el seu contingut. N’hi ha prou en donar nom com aquest, sense aquesta extensió, al paràmetre page de l’URL d’un lloc sota SPIP per provocar l’ús d’aquest esquelet.
L’arrel del directori |
formulaires/ |
conté la part html de les etiquetes dinàmiques, esquelets de formularis el codi PHP dels quals figura a dins del directori ecrire/balise |
icones_barre/ |
conté les imatges destinades a il·lustrar la barra tipogràfica |
images/ |
imatges de l’espai privat |
javascript/ |
llibreries javascript (jQuery, barra tipogràfica, ...) |
modeles/ |
esquelets que es poden cridar amb l’etiqueta #MODELE o amb les dreceres <article6|modele> |
polices/ |
fonts utilitzables per les imatges tipogràfiques Imatges tipogràfiques |
vignettes/ |
miniatures estàndards pels diversos tipus de documents que es poden associar a un article |
Funcions del directori ecrire i els seus subdirectoris
El directori ecrire té diversos subdirectoris que es componen de fitxers PHP que defineixen funcions i continuen eventualment, però rarament, en una inicialització en el moment de ser carregats (aquestes excepcions són cridades a desaparèixe). Els arxius que es troben a nivell del directori principal són els més importants a comprendre si es vol contribuir amb SPIP. Es tracta de inc_version.php,
public.php
i
index.php.
L’arxiu
ecrire/inc_version.php
inicialitza les constants i les variables globals necessàries pel funcionament d’SPIP, sobretot d’aquelles que asseguren la seva portabilitat en les diverses plataformes.
Bastant aviat durant la seva càrrega, inclou el fitxer inc/utils.php, on hi figuren les funcions indispensables a SPIP, un arxiu fora de distribució anomenat mes_options.php i que permet modular aquesta inicialització sense haver de modificar l’arxiu inc_version.php. En particular, es possible en aquest arxiu personal invocar la funció spip_initialisation
per definir els directoris de dades i disposar d’aquesta manera de diversos llocs sota SPIP que utilitzin una única distribució (la crida estàndard d’aquesta funció, més lluny a dins de
inc_version.php, serà automàticament neutralitzada).
Una altra funció indispensable a SPIP és find_in_path, que fa funcionar el camí d’accés, i també include_spip
que reposa damunt de find_in_path, i charger_fonction
que reposa damunt de include_spip. Tots els arxius d’SPIP són carregats per aquestes dues darreres funcions.
El fitxer ecrire/public.php, cridat per spip.php, té com a funció essencial alliberar les pàgines de l’espai públic, ordenades quan la consulta HTTP comporta (desprès d’una possible reescriptura) el paràmetre page. Aquest script aplica llavors l’esquelet que té per nom el valor d’aquest paràmetre. Envia els encapçalaments HTTP i el contingut obtingut, gestiona els seus possibles errors i llança les tasques de fons amb l’ajuda de la funció cron. Contribuir a l’espai públic d’SPIP consisteix, per tant, simplement en proporcionar nous esquelets, possiblement amb els seus fulls d’estil i les seves imatges.
L’altre paper de ecrire/public.php afecta en cas que la petició HTTP comporti l’argument action. Llavors aplica la funció charger_fonction al valor v d’aquest paràmetre action. Aquesta aplicació té com a resultat carregar el fitxer homònim del directori action, la principal funció del qual action_v_dist s’invoca llavors. Aquests scripts efectuen essencialment escriptures (en base o sobre aquest fitxer) i no retornen, generalment, cap resultat, escapant així a la problemàtica de la configuració de la pàgina.
El fitxer index.php és el fitxer central d’accés als formularis de l’espai privat. Autentifica l’internauta, inicialitza les dades personals i aplica la funció charger_fonction al valor v del paràmetre exec. Aquesta aplicació té per efecte carregar el fitxer homònim del directori exec, la principal funció del qual exec_v_dist s’invoca llavors.
Aquest té la responsabilitat de lliurar la totalitat del flux de sortida, fins i tot els encapçalaments HTTP. Per tant, és possible ampliar SPIP simplement afegint un fitxer PHP en un subdirectori anomenat exec d’un directori que figura a SPIP_PATH.
El directori exec conté exclusivament els fitxers que defineixen les funcions directament invocables pel paràmetre d’URL
exec. El codi PHP d’aquests fitxers no ha d’accedir mai en escriptura a la base de dades (les excepcions a aquesta regla estan en vies de desaparèixer). A l’inrevés, hi accedeix i molt en lectura per tal de verificar els drets del demandant i determinar les dades a visualitzar. Si es vol veure SPIP sota arquetip Modèle-Vue-Controleur, els fitxers de
exec exerceixen el paper de Controler. Si es vol veure SPIP sota arquetip (Print(Eval(Read))) de Lisp, és la part Read. Al final, aquest directori hauria d’esdevenir un directori d’esquelets.
Es demana a les noves contribucions d’Spip que pensin en aquest objectiu durant les seves redaccions.
El directori action, que ja hem tractat, conté essencialment els scripts que accedeixen en escriptura a la base de dades. Si es vol veure SPIP sota l’arquetip Modèle-Vue-Controleur, els fitxers de action emplenen el paper de Modèle. Si es vol veure SPIP sota l’arquetip (Print(Eval(Read))) de Lisp, és la part Eval.
Allà encara, contribuir a SPIP consisteix en escriure scripts i cridar-los per mitjà de formularis construïts amb la funció generer_action_auteur
assegurar la seguretat d’accés a aquests scripts, que, a la inversa, invocaran la funció securiser_action_auteur
per verificar els drets del demandant. Aquesta arquitectura permet calcular aquests drets només en la construcció de formularis cridant els scripts d’accés en escriptura: més que recalcular tots els drets, aquests scripts verifiquen simplement que la clau que figura en els arguments és la mateixa que la que ells recalculen a partir dels altres arguments, de la identitat del demandant i d’un valor aleatori renovat periòdicament. Aquests scripts generalment no retornen cap resultat, per tant aquí no hi ni codi codi HTML, ni crida a la funció echo (les excepcions estan en vies de desaparició).
Per contra, són cridats sovint amb un paràmetre HTTP anomenat redirect, demanant una redirecció que llavors serà operada automàticament per public.php, que envia un estat HTTP 204 en absència d’aquest paràmetre.
En el cas dels formularis construïts amb la funció ajax_action_auteur, aquesta redirecció condueix a l’script homònim a dins del directori exec. Aquest segon script es redueix sovint a carregar el fitxer homònim a dins del directori inc, cridar la seva funció principal el resultat de la qual es retornat al client per mitjà de l’intermediari de la funció ajax_retour. És molt fàcil també ampliar SPIP en mode AJAX beneficiant-se d’aquesta infraestructura.
El directori inc, el més voluminós, conté essencialment les funcions que construeixen les pàgines de l’espai privat reenviades al client, havent d’estar aquestes funcions al final dels filtres utilitzats pels fitxers de exec quan seran esquelets. Si es vol veure SPIP sota l’arquetip Modèle-Vue-Controleur, els fitxers de inc omplen el paper de Vue. Si es vol veure SPIP sota l’arquetip (Print(Eval(Read))) de Lisp, és la part Print.
No obstant, aquest directori conté igualment moltes funcions aplicables més aviat del Controle i, per tant, haurà de ser reorganitzat. La major part de fitxers de inc són carregats mitjançant charger_fonction, i aquest serà el cas de tots al final.
Cap de les funcions d’aquest directori utilitza suposadament echo.
Les contribucions a SPIP han de respectar aquestes regles a partir d’ara.
El directori install conté exclusivament les funcions necessàries per la instal·lació d’SPIP. Cada etapa pot ser recarregada o completada per altres, la funció principal de exec/install.php utilitzant aquest directori segons el mateix principi que ecrire/index.php amb el directori
exec.
El directori urls conté arxius que defineixen cadascun el mateix joc de funcions de reescriptura d’URL.
Es tracta de funcions que calculen, a partir d’un índex numèric en una taula de la base de dades, un marcador més fàcil de llegir i escriure que la crida de l’script PHP efectivament operat pel servidor HTTP per aquest índex i aquesta taula. Encara allà, n’hi ha prou en afegir un arxiu en aquest directori per obtenir un nou joc, el nom del qual serà presentat en el panell de control de l’espai privat gestionant els tipus d’urls (abans d’SPIP 2.0, aquest panell no existia i aquests arxius eren utilitzats per la global type_urls).
El directori lang conté exclusivament fitxers de dades, taules que indiquen la traducció, per totes les llengües reconegudes d’SPIP, de tots els arguments que la funció _T, definida a inc/utils.php, és capaç de rebre. Els fitxers són carregats exclusivament per les funcions de inc/lang.php. Per declarar una nova llengua a SPIP n’hi ha prou traduint els fitxers de referència *fr* donant un nom convencional als fitxers obtinguts.
El directori charset conté ell també exclusivament fitxers de dades, taules que permeten passar d’un codi de caràcters a un altre (utf, iso, ascii, entités html etc). Són llegits exclusivament per les funcions de inc/charsets.php. Allà també n’hi ha prou en afegir un fitxer per disposar d’una nova codificació, però SPIP propose tots aquests utilitzats correntment, d’aquesta manera una intervenció d’aquest tipus és molt rara.
El directori base conté les funcions d’interfícies entre PHP i els servidors SQL que SPIP pot cridar.
Especialment, el fitxer genèric abstract_sql.php conté les funcions que cal utilitzar per dialogar amb els servidors SQL; és per això que les funcions de base PHP no s’han d’utlitzar directament per evitar problemes en la portabilitat.
Evidentment no ha de figurar cap codi MIME en aquest directori.
El directori req conté els transports efectius des del servidor SQL virtual d’SPIP cap als servidors reals (MySQL, PG) i assimilats (SQLite).
El directori balise conté els arxius PHP associats a les etiquetes dinàmiques d’SPIP.
El seu nom és homònim al de l’esquelet de dist/formulaires. Completar l’espai públic d’SPIP per un formulari F consisteix en crear un fitxer F.html a dins del seu SPIP_PATH i un fitxer F.php a dins d’un subdirectori balise del seu SPIP_PATH.
La funció d’aquest arxiu PHP és capturar les dades demanades per aquest formulari, i, eventualment, tornar-lo a mostrar per complementar en cas de dades invàlides. És sens dubte el tipus de contribució a l’espai públic més difícil de realitzar, ja que la mecànica que serveix de base exigeix dos passos de PHP i, per tant, cal comprendre molt bé les respectives funcions.
Abans que existís aquest mecanisme, l’estratègia de desenvolupament del formulari consistia en escriure esquelets que impliquessin instruccions PHP. Actualment encara és possible fer-ho, però el resultat serà poc eficaç ja que no es posa mai a la memòria cau; i tampoc eximeix de comprendre els dos passos de PHP intrínsecs al fenomen.
El directori public conté el compilador dels esquelets. És una part del codi força complicada, però a partir d’SPIP 1.8 gaudeix d’una interfície de programació que permet que aquest compilador sigui extensible sense necessitat de comprendre’n tots els detalls. La descripció més completa la trobareu aquí.
El directori lib conté subdirectoris de biblioteques desenvolupades externament a SPIP però que ens poden ser necessàries. Actualment, només es proporciona sistemàticament la biblioteca safehtml, proporcionant eines per fer més segures pàgines que cridin scripts. Per col·laborar en aquesta part, s’ha d’anar directament al seu lloc Web.
Últim punt: la majoria dels fitxers d’SPIP s’utilitzen per mitjà de charger_fonction que carrega un fitxer i crida la seva funció homònima que suposadament està definida allà. Per tant, el nom d’un fitxer PHP s’ha de compondre exclusivament de caràcters acceptables per un nom de funció PHP: s’evitarà per tant el signe menys, el punt, etc.
Regles de programació
SPIP ha arrencat a l’època en que PHP transformava automàticament en variables globals els paràmetres HTTP. Aquest estil de programació suïcida ha estat abandonat per PHP4. SPIP ha seguit una evolució paral·lela, però desplaçada en el temps. Per bé que el codi actual no segueix encara les regles que s’han de seguir, es demana a les contribucions de respectar-ho des d’ara mateix, sense esperar que SPIP ho acabi de fer aquí o allà.
Es pot llegir atentament el fitxer ecrire/articles.php, el més proper de les especificacions que segueixen.
- Afavorir l’escriptura per funcions. La filosofia del programari lliure és que pugui ser utilitzat en un màxim de contexts diferents; per tant, el codi s’ha d’escriure sota l’òptica de que es pugui tornar a utilitzar fora del seu context inicial de desenvolupament. L’escriptura per funcions no referencia cap variable global i no efectua cap crida a echo
o print i garanteix una càrrega silenciosa i una crida sense efectes secundaris indesitjables.
- Evitar al màxim l’ús de variables globals. Aquestes són responsables de moltes fallades de seguretat i d’impossibilitat de reutilització del codi. Les alternatives al seu ús són:
— la constant, que té l’avantatge d’assenyalar al lector que aquest valor no canviarà durant tota la duració del script;
— la variable estàtica, que té l’avantatge d’assenyalar al lector que es tracta d’un valor de llarga vida però que només interessa la funció que la declara. .
- Escriure codi que no produeixi cap error ni advertiment en mode error_reporting(E_ALL). Això facilita la posada a punt en cas d’una variable involuntàriament definida. Si es té realment necessitat d’executar codi a fora d’aquest mode, utilitzarem el subterfugi @ limitant-lo al màxim a la porció de codi problemàtic, i preveient un missatge d’error al diari, utilitzant la funció spip_log.
- Comentar el context, no el text. No serveix per a res citar el nom de les seves variables i funcions, ni les funcions PHP descrites al manual: els comentaris com bucle sobre la taula de valors al davant d’un foreach no fan més que ampliar inútilment la mida dels fitxers. Per contra, és desitjable indicar el tipus d’arguments (com que PHP és un llenguatge escrit dinàmicament, s’endevina difícilment) i la seva presumible propietat a l’entrada de la funció (per exemple: non nul). Quan un error difícil és corregit o anticipat, explicar el perquè el codi inicial era incorrecte per tal d’evitar que una reescriptura posterior el torni a introduir creient que s’està optimitzant. Finalment, com que SPIP es desenvolupa en francès, cal evitar els termes que no figuren als diccionaris d’aquesta llengua per tal de facilitar-ne la comprensió a aquells que no el tenen com a llengua materna.
- Anomenar racionalment les funcions i variables. L’organització del codi d’SPIP es fonamenta més aviat en la fragmentació en directoris dedicats que no pas en regles de nomenclatura estrictes, però s’evitarà en qualsevol cas les incoherències com el multi-lingüisme a l’interior d’un nom. Les funcions d’un mateix tendiran a tenir un prefix o un sufix comú, inspirat amb el nom del fitxer.
- Testejar en un màxim de configuracions. No oblideu que SPIP ha de funcionar damunt de qualsevol plataforma, doit fonctionner sur toute plate-forrme, tant pel que fa a la banda del client com la del servidor. A la vostra màquina hi ha necessàriament diversos navegadors. Proveu el vostre codi com a mínim en dos d’ells. Quan una plataforma forci una escriptura estranya, mencinar-ho explícitament, precisant-ne la versió i la data de la prova.
Regles de presentació i d’escriptura
SPIP es preocupa de la qualitat tipogràfica de les pàgines que envia als clients HTTP, per tant es preocupa, també, de la qualitat dels seus propis fitxers. És recomanat respectar les regles que trobarem tot seguit, força estàndard en programació.
Presentació
- El text de les funcions ha de ser curt, idealment inferior a la mida d’una pantalla estàndard, per tal que la totalitat de la seva estructura sigui visible d’un sol cop d’ull.
- El text de les funcions ha d’estar indentat, cada bloc contingut a l’interior d’un parell de claus i reforçat per una unitat d’indentació suplementària, aplicant-se, evidentment, de forma recursiva.
- Agafar el caràcter de tabulació per indentar, ja que això permet a cadascú escollir lliurement la profunditat d’indentació a dins de les opcions del propi editor de textos.
- Quan una instrucció PHP ocupa diverses línies, deixar una línia en blanc abans i després;
- Els fragments HTML, ja es tracti de transicions (<?php i ?>) o d’expressions PHP seran blocs XHTML complerts:
evitar posar una etiqueta d’obertura a l’inici d’una funció i el seu tancament al final, això no permet desplaçar fàcilment aquest parell en cas de necessitat.
Tipografia
- Quan s’utilitzin els parèntesi o els claudàtors, evitar els espais després de l’obertura i el tancament.
- En les expressions PHP deixar un espai a banda i banda dels operadors binaris (+, =, *, AND, ...).
- Els operadors unaris (!, ...) han d’anar enganxats als paràmetres als que s’apliquen.
- Per convenció, quan es crida una funció, no hi ha d’haver cap espai al davant del parèntesi d’obertura: « f($x) » i no « f ($x) ». Per contra, i per distingir-ho bé, es deixa un espai al davant del parèntesi quan es tracta d’una estructura de control integrada al llenguatge: « if (!$x) » i no « if(!$x) ».
- Les comes i els punts i coma van seguits per un espai; mai el porten al davant.