Urganizazione di u còdice

Dipoi a versione 1.9, hè pussìbule mudificà u cumpurtamentu di SPIP senza tuccà u so còdice, usendu u percorsu d'accessu definitu da a custante SPIP_PATH. Cusì deve uperà qualsìasi estensione di SPIP da chì una prova d'integrazione possi esse smessa solu definiscendu u percorsu d'accessu cù un novu valore, postu chì l'arburatura di SPIP hè di règula da lettura sola. Sè vo site scunvintu chì fendu cusì un certu cumpurtamentu ùn si pò ottene, scrivite puru à a lista di ragiunata spip-dev.

I cuntributi à prò di SPIP sò da discrive cù un artìculu nant'à Spip-Contrib è u so cuntentu da pone, sia da robba alleata à st'artìculu, sia, per fà megliu, nant'à spip-zone chì furnisce un servore Subversion piluttatu da Trac.

Da vulè cuntribuisce à SPIP, bisogna à capisce l'urganizazione di sti cartulari è u scopu di sti schedari. In più di u presente artìculu, puderà omu leghje cù assai interessu quellu chì annunciò SPIP 1.9, iniziatore di st'urganizazione.

A ràdica d'una arburatura SPIP cuntene principalmente:

- un schedariu spip.php, alias index.php, chì gestisce a cumpatibulità cù l'anziane versioni, carichendu u schedariu d'inizializazione ecrire/inc_version.php è lascendu sùbbitu viaghjà u script principale ecrire/public.php;

- un cartulare ecrire chì cuntene solu schedari interpretati da u servore (PHP è SQL);

- unu o parechji cartulari (secondu e versioni) chì cuntenenu schedari interpretati da u cliente (HTML, Javascript, foglie di stile, imàgini di diversi furmati) cù i mudelli di paginatura. Sti mudelli venenu interpretati da i dui lati: sò schedari cumposti da un furmatu MIME, cumplettatu da qualchì direttiva SPIP, è venenu uperate quelle direttive da u servore da rimandà à u cliente un testu schiettu MIME (u più spessu HTML, ma dinò RSS, SVG, ICS etc).

- quattru cartulari vioti tempu a stallazione, chì cunteneranu i dati, pruvisori o permanenti, necessari à a vita di u situ.

Scopu di i cartulari prive è squelettes-dist cù i so sottucartulari

Cuntenenu schedari impurtantìssimi per a prisentazione di SPIP, u primu per u spaziu privatu, l'altru per u situ pùbblicu. Prima di SPIP 2.0, ùn fecianu chè unu, chjamatu dist. Cuntenenu assai sottucartulari spiecati quì sottu:

cartulare	scopu
/	cuntene i mudelli. U so nome finisce cù .html per ragioni stòriche, ma pò ancu cuntene altra robba. Basta à dà tale nome, senza estensione, à u paràmetru page di l'URL d'un situ fattu cù SPIP, è vene adupratu u mudellu chì porta stu nome. Stu cartulare cuntene dinò e foglie di stile (d'estensione .css) chì definiscenu u vestitu predefinitu
furmulari/	cuntene a parte html di e balise dinàmiche, mudelli di furmulari chì u so còdice PHP hè cullucata in u cartulare ecrire/balise
icones_barre/	cuntene l'imàgini chì vanu nant'à l'asta tipugràfica
images/	imàgini di u spaziu privatu
javascript/	librerie javascript (jQuery, asta tipugràfica, ...)
modeles/	mudelli chì ponu esse chjamati da a balisa #MODELE o cù l'accurtatoghji
polices/	pulizze di caràtteri chì ponu esse aduprate per l'imàgini tipugràfiche
vignettes/	imaginette standard per i ducumenti chì ponu esse alleati à un artìculu

Scopu di u cartulare ecrire cù i so sottucartulari

U cartulare ecrire cuntene parechji sottucartulari cumposti da schedari PHP chì definiscenu funzioni è chì, caricati ch'elli sò, di raru prucedenu qualchì inizializazione (sò per smarrice quelli chì a facenu sempre). Da cuntribuisce à SPIP, i più impurtanti da capisce sò i schedari cullucati in u cartulare principale, vale à dì inc_version.php, public.php è index.php.

U schedariu ecrire/inc_version.php inizializeghja e custante è e variàbile glubale necessarie à u viaghjà di SPIP, in particulare quelle chì assicureghjanu u so bon'tramutu nant'à i diversi sistemi. Tempu caricatu, include u schedariu inc/utils.php, duve figureghjanu e funzioni indispensèvuli à SPIP, un schedariu fora arburatura chjamatu mes_options.php chì permette di graduà l'inizializazione senza duvè mudificà u schedariu inc_version.php. In particulare, in stu schedariu persunale hè pussìbule chjamà a funzione spip_initialisation per definisce i cartulari di dati, è cusì dispone di parechji siti fatti cù SPIP chì adopranu un'arburatura cumuna (a chjama standard à sta funzione, più in là in inc_version.php, serà smessu in autumàticu). Altre funzioni indispensèvuli à SPIP sò find_in_path, chì gestisce u percorsu d'accessu, è include_spip chì s'arremba à find_in_path, è charger_fonction chì s'arremba à include_spip. Tutti i schedari di SPIP veneu caricati da ste duie funzioni.

U schedariu ecrire/public.php, chjamatu da spip.php, s'incaricheghja principalmente di furnisce e pàgine di u spaziu pùbblicu, cherse quandu chì a richiesta HTTP si porta (dopu eventuale riscrittura) u paràmetru page. Stu script và è piglia tandu u mudellu chì u so nome hè u valore di u paràmetru. Manda l'intestatura HTTP è u cuntenutu racoltu, gestisce l'eventuali errori è lancia i lavori di sottufondu usendu a funzione cron. Cuntribuisce à SPIP, vole dì simpliciamente furnisce mudelli novi, cù e so foglie di stile è e so imàgini, s'ella casca.

L'altru scopu di ecrire/public.php vene quandu chì a richiesta HTTP si porta l'argumentu action. Tandu appiccica à a funzione charger_fonction u valore v di st'argumentu action. Vene caricatu u schedariu di listessu nome da u cartulare action, è vene chjamata a so funzione principale action_v_dist. Sti scripts ùn facenu guasi chè scritture (in basa o in schedari) è di règula ùn ritornanu risultatu, è cusì ùn toccanu mancu appena a paginatura.

U schedariu index.php hè u schedariu centrale d'accessu à i furmulari di u spaziu privatu. Ricunnosce l'utilizatore, inizializeghja i so dati persunali è accoppia à a funzione charger_fonction u valore v di u paràmetru exec. Vene caricatu u schedariu di listessu nome da u cartulare exec, è vene chjamata a so funzione principale exec_v_dist. Questa hè incaricata di furnisce u flussu sanu sanu d'esciuta, cumpresa l'intestatura HTTP. Hè dunque pussìbule d'accresce SPIP, solu aghjunghjendu qualchì schedariu PHP in un sottucartulare di nome exec d'un cartulare cullucatu in SPIP_PATH.

U cartulare exec cuntene solu i schedari chì definiscenu e funzioni da chjamà direttamente cù u paràmetru d'URL exec. U còdice PHP di sti schedari ùn deve mai accede à a basa di dati in scrittura (sò per smarrisce quelle chì a facenu sempre). À l'incuntrariu, assai ci accede in lettura, da cuntrullà i diritti di quellu chì dumanda, è da stimà i dati da fà cumparisce. Sì omu vole fighjà SPIP cù a mudellatura Modèle-Vue-Controleur, i schedari di exec anu u scopu di Controleur. Sì omu vole fighjà SPIP cù a mudellatura (Print(Eval(Read))) di Lisp, currisponde à a parte Read. Da quì à pocu cuntenerà stu cartulare solu mudelli. Dumandemu chì i cuntributtori tenghinu à contu issu scopu in u so modu di pensà è di scrive i nuvelli cuntributi.

U cartulare action, si n'hè parlatu digià, ùn cuntene guasi chè i scripts chì accedenu in scrittura à a basa di dati. Sì omu vole fighjà SPIP cù a mudellatura Modèle-Vue-Controleur, i schedari di action anu u scopu di Modèle. Sì omu vole fighjà SPIP cù a mudellatura (Print(Eval(Read))) di Lisp, currisponde à a parte Eval. Quì dinò, cuntribuisce à SPIP, vole dì scrive sìmuli scripts, è fà li chjamà da furmulari custruiti cù a funzione generer_action_auteur chì s'incaricheghja di l'accessu à sti scripts, chì elli chjameranu a funzione securiser_action da verificà i diritti di quelli chì dumanda. St'architettura permette chì i diritti sianu verificati una volta sola, tempu custruiti i furmulari chì chjamanu i scripts d'accessu in scrittura: nanzi chè di turnà à verificà tutti i diritti, sti scripts si cuntenteranu di fighjà chì a chjave cullucata da argumentu sia listessa à quella ricalculata à parte si di l'altri argumenti, di l'identità di quellu chì dumanda, è d'un valore à l'azardu rinuvellatu ogni tantu. Di règula sti scripts ùn ritornanu risultatu, ùn ci hè custì nisun còdice HTML nè chjama à a funzione echo (sò per smarrisce quelli chì a facenu sempre). Invece, à spessu venenu chjamati cù un paràmetru HTTP di nome redirect, dumandendu una rindirizzata, fatta tandu in autumàticu da public.php, è chì manda un statutu HTTP 204 in assenza di quellu paràmetru. In u casu di i furmulari custruiti cù a funzione ajax_action_auteur, sta rindirizzata manda versu u script di listessu nome in u cartulare exec. Stu secondu scrittu si cuntenta u più spessu di caricà u schedariu di listessu nome in u cartulare inc, di chjamà a so funzione principale chì ritorna u risultatu, rispostu à u cliente da a funzione ajax_retour. Cusì vene assai fàciule di fà cresce SPIP in modu AJAX, aduprendu st'architettura.

U cartulare inc, u più grossu, ùn cuntene guasi chè funzioni chì custruiscenu e pàgine di u spaziu privatu mandate à u cliente. Da quì à pocu ste funzioni diventeranu stacci usati da i schedari di exec quandu quessi diventeranu mudelli. Sì omu vole fighjà SPIP cù a mudellatura Modèle-Vue-Controleur, i schedari di inc anu u scopu di Vue. Sì omu vole fighjà SPIP cù a mudellatura (Print(Eval(Read))) di Lisp, currisponde à a parte Print. Ma stu cartulare cuntene dinò tante funzioni piuttostu di scopu Controle è tuccherà dunque à turnà à assestà lu. A maiò parte di i schedari di inc sò incaricati da charger_fonction, è da quì à pocu tutti cusì feranu. echo ùn hè adupratu da nisuna funzione di stu cartulare. Dumandemu chì ad avà rispettinu ste règule tutti i cuntributi.

U cartulare install cuntene solu e funzioni necessarie à a stallazione di SPIP. Ogni tappa pò esse soprascritta o cumplettata da altre, postu chì a funzione principale di exec/install.php adopra stu cartulare secondu u listessu spìritu chè ecrire/index.php adopra u cartulare exec.

U cartulare urls cuntene schedari chì definiscenu ognunu u listessu ghjocu di funzioni di riscrittura d'URL. Si tratta di funzioni chì calculeghjanu, à parte si d'un ìndice numèricu postu in una tàvula di a basa di dati, una «marca», più fàciule à scrive è à leghje di pettu à a chjama à u script PHP uperata da u servore per st'ìndice quì è sta tàvula quì. Quì dinò, basta à aghjunghje un schedariu in stu cartulare per ottene un nuvellu ghjocu, è u so nome venerà à cumparisce in u pannellu di cunfigurazione di u spaziu privatu chì gestisce i tippi d'urls (prima SPIP 2.0, ùn esistia ancu stu pannellu è issi schedari eranu usati da a glubale type_urls).

U cartulare lang cuntene solu schedari di dati, tavuloni chì indettanu a traduzzione, per tutte e lingue cunnisciute di SPIP, di tutti l'argumenti ch'ella pò riceve a funzione _T, definita in inc/utils.php. Venenu caricati i schedari solu da e funzioni di inc/lang.php. Per dichjarà una nuvella lingua SPIP, basta à traduce i schedari di riferenza *fr* dendu un nome cunvenutu à i schedari cupiati, vale à dì usendu u còdice di a nuvella lingua.

U cartulare charset anch'ellu cuntene solu schedari di dati, tavuloni chì permettenu di passà d'un còdice di caràtteri à un altru (utf, iso, ascii, entità html etc). Sò letti solu da e funzioni di inc/charsets.php. Quì dinò, per dispone d'un nuvellu còdice, basta à aghjunghje un schedariu, bench'ellu pruponga SPIP tutti quelli usati di règula. Serà bella scarsa quessa a faccenda.

U cartulare base cuntene e funzioni d'interfaccia trà PHP è i servori SQL ch'ellu pò chjamà SPIP. In particulare, u schedariu genèricu abstract_sql.php cuntene e funzioni ch'ellu bisogna à aduprà pè discorre cù i servori SQL, invece di e funzioni di basa di PHP chì ùn ci vole tandu à aduprà direttamente, da chì u prugrammu fermi fàciule tramutèvule. Di sicuru ùn deve figurà nisun còdice MIME in stu cartulare.

U cartulare req cuntene e passarelle da u servore SQL virtuale di SPIP versu i servori veri (MySQL, PG) è cusì cunsiderati (SQLite).

U cartulare balise cuntene i schedari PHP assuciati à e balise dinàmiche di SPIP. U so nome hè uguale à quellu di u mudellu di squelettes-dist/formulaires. Cumplettà u spaziu pùbblicu di SPIP cù un furmulariu F, ghjè creà un schedariu F.html in u so SPIP_PATH è un schedariu F.php in un sottucartulare balise di u so SPIP_PATH. U scopu di stu schedariu PHP hè di riceve a robba inserita in stu furmulariu, è sì bisogna, di rifà cumparisce u furmulariu cumplettatu, in casu di gattiva stampittata. À colpu sicuru, questu hè u cuntributu à u spaziu pùbblicu u più diffìciule à uperà, perchè richere quella mecànica in sottu dui giri d'eseguimentu di PHP chì tocca omu à capisce bè u scopu d'ogni parte. Prima ch'ella esistissi sta mecànica, a strategia di sviluppu di furmulariu era di scrive mudelli chì cuntenianu istruzzioni PHP. Si pò sempre fà la ma averà pocu effettu perchè mai postu in cache; è mancu appena impedisce à omu di pruvà à capisce i dui giri PHP chì facenu viaghjà l'affare...

U cartulare public cuntene u cumpilatore di i mudelli. Hè una parte di u còdice assai cumplicata, ma dipoi SPIP 1.8 esiste un'interfaccia di sviluppu chì rende stu cumpilatore sanu sanu allerghèvule senza richere di capisce lu à fondu. Quì ne truverete a descrizzione chì tene a strada à pocu pressu...

U cartulare lib cuntene sottucartulari di bibbiuteche sviluppate fora di SPIP ma chì ponu ancu ghjuvà. Oghje ch'hè oghje, solu vene furnita sempre a bibbiuteca safehtml, chì prupone arnesi di sicurizazione di pàgine chì cuntenenu scripts. Per cuntribuisce à sta parte quì, andate puru direttamente à visità à elli.

Per compie: a maiò parte di i schedari SPIP venenu chjamati da charger_fonction, chì caricheghja qualchì schedariu è chjama a so funzione di listessu nome chì nurmalamente hè stata definita. Vene à dì chì u nome d'un schedariu PHP deve esse cumpostu solu di caràtteri auturizati per un nome di funzione PHP: megliu à lascià corre i caràtteri «-», «.» etc.

Règule di prugrammazione

Hè natu SPIP à un'èpica chì PHP trasfurmava in autumàticu i paràmetri HTTP in variàbili glubale. Quessu u mendu di prugrammazione da lampà si in portu fù abbandunatu, toccu PHP4. Tandu seguitò SPIP listessu chjassu (micca à esse abbandunatu!) ma appenuccia attempatu. Benchì u còdice attuale ùn ubidisca micca sempre à e règule sposte quì sottu, dumandemu chì i cuntributi futuri e rispèttinu ad avà, senza aspettà chì SPIP appia scunfinitu tutti i punti da turnà à scrive quindi è culandi. Da leghje cù cura u schedariu ecrire/articles.php, u più strettu à e specìfiche sposte quì sottu.

- Favurizà a scrittura di funzioni. A filusufia d'un prugrammu lìberu essendu d'esse praticatu in u più pussìbule di cuntesti sferenti, deve esse scrittu u còdice cù l'idea d'aduprà lu torna fora di u so cuntestu iniziale di sviluppu. A scrittura di funzioni ùn riferisce nisuna variàbile glubale, è mancu chjama à echo o à print. Cusì guarantisce un viaghjà silenziosu è senza effetti secondi dispiacèvuli.

- Lascià da cantu quant'ellu si pò e variàbili glubale. Sò ripunsèvule quesse di tante sgheze di sicurezza è d'impussibulità di turnà à aduprà u còdice. Invece ponu esse aduprate:

— a custante, interessante perchè ch'ella indetta à u lettore ch'ellu ùn cambierà u so valore durante tuttu u tempu ch'ellu hè eseguitu u script;

— a variàbile stàtica, interessante perchè ch'ella indetta à u lettore ch'ellu si tratta d'un valore à longu andà, ma ristrettu à a funzione chì l'hà dichjarata.

- Scrive còdice chì ùn crea nè errore nè avertimentu in modu error_reporting(E_ALL). Quessa faciliteghja l'affari in casumai chì una variàbile ùn sia definita apposta. Sè vo avete veramente necessità d'eseguisce còdice fora di stu modu, aduprate puru u caràtteru @ limitatu à u pezzu di còdice chì dà fastidiu, è accunciate qualchì messagiu d'errore in u ghjurnale, aduprendu a funzione spip_log.

- Cummentà u cuntestu, è micca u testu. Ùn ghjova à nunda di ripete u nome di e variàbili è funzioni in e scrivacciulate, nè mancu e funzioni PHP digià spiecate in u so manuale: i cummenti à l'usu ciclu nant'à u tavulone di valori davant'à un foreach sò diciulate chì empienu i schedari per nunda. Invece vene più amparatoghja d'indettà u tippu d'argumenti (essendu PHP un linguagiu tippatu in dinàmicu, s'induvineghja piuttostu male...) cù e so pruprietà aspettate in entrata di a funzione (per esempiu: ùn deve esse nullu). Quand'ellu vene currettu o antivistu qualchì bug diffìciule, dite puru perchè ch'ellu era sbagliatu u còdice, di modu chì qualchì futura riscrittura ùn torni micca à sciaccà lu, vulendu fà bè. Infine, sviluppatu in francese ch'ellu hè SPIP, lasciate puru da cantu e parulle chì ùn figureghjanu micca in i dizziunari di sta lingua, da ch'ella sia più capiscitoghja per quelli chì ùn hè micca a so lingua materna.

- Dà nomi à e funzioni è e variàbili cù sensu è ragione. L'urganizazione di u còdice di SPIP hè più fundata nant'à u spartimentu in cartulari dedicati chè nant'à strette règule di nomi, ma quantunque pruverete à lascià da cantu certe incuerenze, cum'è per esempiu u multilinguìsimu dentr'à un nome. E funzioni d'un listessu schedariu puderanu avè qualchì prefissu o suffissu cumunu, ispiratu da u nome di u schedariu.

- Fà e prove nant'à u più pussìbule di cunfigurazioni. Tenite à mente chì SPIP deve pudè viaghjà nant'à qualsìasi sistema, cliente o servore ch'ellu sia. Per forza avete parechji navigatori nant'à u vostru urdinatore, allora pruvate ne omancu dui. Quant'ella si pò, pruvate dinò parechji òspiti. Sì qualchì sistema dà una scrittura strana, mintuvate la puru, precisendu a so versione è a data chè vo l'avete prova.

Règule di prisentazione è di scrittura

Hè primurosu SPIP di a qualità tipugràfica di e pàgine ch'ellu manda à i clienti HTTP, vene à dì ch'ellu hè primurosu altr'è tantu di quella di i so propri schedari. Arricumandemu ch'elle sianu rispettate e règule quì sottu, abbastanza usuale in prugrammazione.

Prisentazione

- Deve esse cortu u testu di e funzioni, quantu omu pò, più cortu chè a taglia cumuna d'un screnu, da chì a struttura sana sana di ogni funzione si possi vede d'un solu sguardu.

- U cuntenutu testu di e funzioni deve esse sempre indiziatu d'un passu à diritta. Dentr'à stu cuntenutu, ogni pezzu postu frà «aculate» ({}) deve esse indiziatu anch'ellu d'un passu in più, è tira avanti per ogni livellu d'«aculate».

- Aduprate puru u caràtteru di tabulazione per indizià u testu, perchè permette di pudè definisce a prufundezza di i passi frà i paràmetri di u so editore di testu, quale ellu sia.

- Quandu un'istruzzione PHP corre nant'à parechje ligne, mettite ci puru una ligna bianca prima è dopu;

- i pezzùculi HTML, transizioni ( è ?>) o spressioni ch'elli fussinu, seranu pezzi XHTML sani: ùn mettite puru micca balisa da apre in principiu di funzione, è balisa da chjode in coda, perchè chì ùn vene più cusì fàciule à spiazzà a funzione, s'omu ne hà u bisognu.

Tipugrafia

- Quandu omu adopra caràtteri parèntesi o ancini, ùn mettite puru micca spazi dopu à quellu chì apre, nè prima di quellu chì chjode.

- In e spressioni PHP, lasciate puru un spaziu da ogni latu di l'uperatori binari (+, =, *, AND, ...).

- L'uperatori unari (!, ...) devessenu appiccitati à u paràmetru à chì venenu appiecati.

- Da cunvenuta, quandu vene chjamata qualchì funzione, ùn ci hè spaziu davanti a parèntesi chì apre : « f($x) » invece di « f ($x) ». À l'incuntrariu, da ch'ella sia bella diferenziata, si lascia un spaziu davanti a parèntesi quand'ellu s'agisce d'una variàbile di cuntrollu integrata à u linguagiu: « if (!$x) » invece di « if(!$x) ».

- Dopu à vìrgule è punti vìrgule vene un spaziu. Invece davanti ùn li ne vene.