Forse non tutti sanno a cosa serve il file include/common.php(incluso nel mainfile.php). Brevemente, potremo dire che ci prepara belli e pronti, degli oggetti che possiamo sfruttare per richiedere servizi al kernel di xoops per le nostre pagine. Un qualcosa di simile alle chiamate di sistema di linux. Sono diversi questi oggetti..e sono molto comodi da usare. In questo tutorial ci occuperemo dell'oggetto $xoopsDB per l'interazione col database di xoops.

Obbiettivi tutorial
Conoscere l'oggetto $xoopsDB per gestire query SQL che interagiscono con xoops-MySQL. Si imparerà a gestire gli errori, a creare query semplificate e query complesse con due tabelle.

Preconoscenze
Per rendere proficua la lettura è consigliata una conoscenza minima di php (variabili, array, cicli) e una infarinatura sui concetti di classe e oggetto. Ottime guide per principianti a mio parare le trovate:
1 Sul sito html.it http://freephp.html.it/guide/lezioni.asp?idguida=10 .
2 Appunti fi informatica libera http://www.pluto.linux.it/ildp/Appunt ... /a2316.html#almltitle3383

Per quanto riguarda il linguaggio SQL:
1 - Conoscenza minima del linguaggio SQL per interagire col database. (vedi tutorial di Defkon1 http://www.xoopsit.net/modules/soapbox/article.php?articleID=28 )

Materiale
Un portale xoops installato in locale "da pasticciare" con una cartella /lab/database create ad hoc nella root. All'interno della cartella database creeremo di volta in volta i file di esempio da "runnare".

Un esempio pratico e funzionante
Subito un esempio pratico che estrae i primi 3 record dalla tabella xoops_users e ne visualizza il nickname per ciascun iscritto. Creiamo un nuovo file query.php e copiamo e incolliamo codice sottostante. In questo esempio il file risiede nella cartella /lab/database/query.php.Il file sarà raggiungibile a questo indirizzo: http://localhost/xoops/lab/database/query.php .

1 - Se le directory sono state create come indicato
2 - Se il codice è stato copiato e incollato senza errori...
...e andate al seguente indirizzo http://localhost/tuonomesitodixoops/lab/database/query.php .

dovrebbe funzionare!

In questo esempio vengono usati tre metodi dell'oggetto: prefix() , query() , fetchArray() . Per ciascuna pagina nuova che andate a creare per usare $xoopsDB, ci sono delle regole da rispettare.
1 - La prima è che la pagina deve avere estensione .php.
2 - Deve avere incluso il mainfile.php.

Perchè mainfile.php? Perchè come credo gia sappiate, mainfile provvedere a creare una connessione persistente al database di xoops (persistente significa che tra una query e l'altra la connessione non viene chiusa ma rimane aperta ed è eseguita con la funzione mysql_pconnect(), p sta per persistent connection) /include/common.php invece, (incluso nel mainfile.php), crea l'oggetto $xoopsDB e lo rende disponibile a tutte le pagine create ex-novo. L'oggetto viene creato alla riga 82 del file common.php:

Per ogni pagina nuova, quindi, , abbiamo già bella e pronta una connessione permanente al database...da sfruttare a piene mani con l'oggetto $xoopsDB.

Vediamo come costruire passo passo query.php

1 - Creiamo una query sql
Ecco una query per iniziare, la si crea e la si memorizza in una variabile php che potete chiamare come volete, solitamente è $query oppure $sql o $rs. E' una query molto semplice e intuitiva:

$sql = "SELECT * FROM xoops_users";

Si usa l'istruzione SELECT * FROM per estrarre l'intero contenuto della tabella xoops_users (* sta per tutti i campi della tabella). Ora che nella variabile $sql è memorizzata la query, diamola in pasto all'oggetto $xoopsDB, nel quale è già attiva una connessione al server MySQL e la selezione del database di xoops. Lanciamo quindi la query:

$result = $xoopsDB ->query ($sql );

In $result viene memorizzato un numero univoco che identifica la query appena eseguita. Se vale 1, la query è stata eseguita con successo, in caso contrario c'è qualche problema. Tratteremo la gestione degli errori più avanti. Continuiamo nella nostra operazione controllando semplicemente se la query ha avuto successo. In questo caso proseguiamo nell'estrazione dei risultati, altrimenti terminiamo lo script:

Per estrarre il recordset abbiamo due metodi a disposizione fetchArray e fetchRow :
Con fetchArray:
$myrow = $xoopsDB ->fetchArray ($result ); //array associativo
echo $myrow['uname'] ; //stamperà dan-tom ad esempio

Con fetchRow:
list ( $uid, $uname, $email) = $xoopsDB ->fetchRow ($result); //array enumerato
echo $uid; //stampo lo uid dell'utente

L'uso dell'uno o dell'altro dipende da ciò che si vuole fare. fetchRow è leggermene più veloce. fetchArray è più comodo poichè i suoi indici sono stringhe.
Per pura curiosità statistica, ho provato a cercare le ricorrenze di $xoopsDB->fetchRow e di $xoopsDB->fetchArray in un sito xoopsato con installati anche svariati moduli (una cinquantina....). Ho ottenuto i seguenti responsi:

1 - $xoopsDB->fetchArray 333 risultati
2 - $xoopsDB->fetchRow 714 risultati

Ma vediamo il nostro script e concludiamolo:

Per comodità lo scriverò con entrambi i metodi
Con $xoopsDB->fetchArray

Con $xoopsDB->fetchArray
In questo caso, usiamo la funzione list con fetchRow

ERRATA CORRIGE:Mi hanno fatto notare che l'array che stampo non è user_arr ma $myrow. Grazie pèer la segnalazione.

Questo è tutto per un primo approccio. Sarebbe interessante, prima di passare alla seconda parte, avere dei feedback trammite i commenti qui sotto, dopo che avete fatto delle prove. Sono a disposizione per chiarimenti. Vi prego cortesemente di avvisarmi nel caso avessi scritto strafalcioni
ALLA PROX!

Buon xoops a tutti!

Dantom