Negli articoli precedenti abbiamo costruito parte di una classe PHP per l’accesso ad un database Firebird. Allo stato attuale delle cose, la nostra classe ci consente di effettuare query, navigare nei resultset ed operare sui campi BLOB.
In questo articolo cercheremo di completare il lavoro provando a capire cosa sono le Transazioni ed implementando un metodo che ci consenta di gestirle al meglio.

Panoramica sulle Transazioni

Nell’operare su basi dati complesse può capitare che per effettuare una determinata operazione sia necessario più di un singolo passo, ad esempio : Un cliente si collega ad un servizio B2B ed inserisce il suo ordine.
Quella che appare come una banale operazione di inserimento in realtà a livello dati potrebbe comportare ad esempio la scrittura della testata d’ordine nella tabella ordini, dei dettagli ordine in un’altra tabella contenente le varie righe, l’aggiornamento della tabella dello storico ordini ed infine l’aggiornamento del campo “data ultima operazione” nella tabella dei clienti.
Come si può facilmente capire, la singola operazione “inserisci ordine” è in realtà composta da 4 sotto-operazioni che dipendono l’una dall’altra in maniera inscindibile : se venissero inserite le righe di dettaglio dell’ordine senza che l’operazione di registrazione della testata fosse andata a buon fine, il database si troverebbe in uno stato inconsistente e non permetterebbe di effettuare l’inserimento restituendo un messaggio di errore.
Per mantenere la coerenza della nostra base dati, nel momento in cui una qualsiasi delle nostre sotto-operazioni dovesse fallire, anche tutte le altre andrebbero annullate.
In questo caso ed in mille altri simili, fare a meno delle Transazioni è praticamente impossibile.
Per definizione quindi, una Transazione è un’insieme di istruzioni SQL che deve essere trattato come un’unita’ “atomica”, cioe’ non scomponibile. Una Transazione viene completata solo se tutte le operazioni che la compongono vengono eseguite con successo. Nel caso in cui una delle operazioni fallisce oppure la Transazione viene esplicitamente annullata, tutte le operazioni precedenti devono essere ritenute nulle, come se non fossero mai state effettuate.
Usare le Transazioni risulta inoltre particolarmente utile nell’implementazione di meccanismi di locking (blocco) per permettere un accesso concorrente ai dati di un database, in quanto le modifiche operate sul database dalle istruzioni di una Transazione non hanno effetto su questo (e quindi non sono visibili ad altre Transazioni) fino a quando la Transazione non viene completata con successo.
Ogni volta che una Transazione viene avviata può concludersi in due modi : Successo o Insuccesso.
In caso di successo tutti gli inserimenti, cancellazioni e aggiornamenti vengono registrati nel database, in caso di insuccesso, il database non sarà in alcun modo modificato e si troverà nello stato immediatamente precedente all’avvio della Transazione.

Avviare una Transazione in Firebird

In Firebird ogni operazione effettuata su un database in realtà è parte di una Transazione. Nel momento stesso in cui viene effettuata una connessione ad un database, viene avviata, in maniera automatica e trasparente ai nostri occhi, una Transazione “di default”, che parte cioè automaticamente, senza bisogno di avviarla tramite istruzioni SQL.
Questo concetto viene spiegato con un esempio nel riquadro 1, e va chiarito da subito che non limita in alcun modo la possibilità di definire proprie Transazioni.
Per avviare manualmente una Transazione, è necessario utilizzare questa istruzione SQL :

SET TRANSACTION <ACCESS MODE> <LOCK RESOLUTION> <ISOLATION LEVEL> <TABLE RESERVATION> <DATABASE SPECIFICATION>

Cerchiamo di capire in maniera sintetica il significato di ciascuno dei parametri passabili all’istruzione :

ACCESS MODE : può essere READ ONLY o READ WRITE, questo parametro descrive il tipo di accesso effettuabile dalla Transazione sulle tabelle del database, se di sola lettura o di lettura e scrittura.

• LOCK RESOLUTION : può essere WAIT o NO WAIT e descrive il tipo di comportamento che la Transazione deve assumere di fronte a record posti in stato di blocco (LOCK). Nel primo caso la Transazione attenderà sino a che il record non sarà sbloccato, nel secondo caso genererà un errore di tipo “LOCK CONFLICT”.
• ISOLATION LEVEL : può essere SNAPSHOT, SNAPSHOT TABLE STABILITY o READ COMMITTED. Questo parametro descrive l’iterazione della Transazione con le altre (eventuali) in corso, il tipo di accesso alle medesime tabelle. Se dichiariamo SNAPSHOT, verrà restituita ad un’altra Transazione la vista del database al momento in cui la nostra è inziata; Indicando SNAPSHOT TABLE STABILITY non verranno consentite modifiche da parte di altre Transazioni alle tabelle che la nostra sta leggendo o updatando; per finire, con READ COMMITTED verrà consentito l’update sull’ultima versione registrata (quindi conclusa con una COMMIT RETAIN, la cui spiegazione viene affrontata nel paragrafo “Terminare una Transazione”) della riga in questione.
• TABLE RESERVATION : consente indicando RESERVING di bloccare immediatamente l’accesso alle tabelle che verranno indicate.
• DATABASE SPECIFICATION : indicando USING si può specificare una serie di database disponibili ai quali questa Transazione può accedere.

Utilizzare la Transazione di default equivale a dichiarare quanto segue :

SET TRANSACTION READ WRITE WAIT ISOLATION LEVEL SNAPSHOT;

Quindi per necessità diverse, saranno diversi i parametri che verranno passati all’istruzione SQL.
E’ possibile anche nominare le Transazioni, per distinguerle l’una dall’altra. L’argomento in se richiederebbe un’articolo a parte e non riguarda direttamente lo scopo del nostro articolo, quindi
ricordo che per approfondire l’argomento un’ottimo strumento gratuito rimane la documentazione di Interbase 6 scaricabile dal sito ufficiale di Firebird :
http://firebird.sourceforge.net/index.php?op=doc&id=userdoc
in particolare il capitolo 4 del libro “EMBEDDED SQL GUIDE” : “WORKING WITH TRANSACTIONS”.

Terminare una Transazione

Ora che è chiaro come viene avviata una Transazione, prima di proseguire, cerchiamo di capire come è possibile terminarla. Come già accennato i due stadi possibili sono successo ed insuccesso.
Le istruzioni associate a questi stadi sono COMMIT e ROLLBACK.
In caso di COMMIT tutti i cambiamenti effettuati all’interno del database diventano permanenti.
In caso di ROLLBACK, tutti i cambiamenti effettuati vengono annullati. Tipicamente, un’istruzione di ROLLBACK viene utilizzata in caso di errore durante lo svolgimento delle operazioni della Transazione per riportare il database allo stato iniziale.
Concludere una Transazione con uno di questi due metodi significa liberare le risorse allocate, rendendo più efficiente e veloce il database.
C’è un’ulteriore parametro passabile ad entrambe le istruzioni, questo è RETAIN.
Se viene aggiunta questa voce ad una delle due istruzioni, la Transazione non viene terminata, ma vengono invece registrate (o annullate) tutte le modifiche effettuate dall’avvio a quel momento. La Transazione rimane dunque aperta, passibile di altre istruzioni SQL comprese nuove COMMIT RETAIN o ROLLBACK RETAIN. E’ facile capire anche come il lanciare immediatamente dopo un comando comprensivo della voce RETAIN un’istruzione di tipo COMMIT o ROLLBACK non produca effetto alcuno se non il terminare la Transazione in corso.

Utilizzare le Transazioni in PHP

Il nostro obiettivo è quello di creare un metodo che consenta alla nostra classe di operare con le Transazioni.
Il supporto che PHP fornisce per gestire le Transazioni di Firebird si basa sul concetto di handle, ed anche se già dovrebbe essere chiaro in quanto parte fondamentale dei precedenti articoli, facciamo un veloce riepilogo : Un handle è un indirizzo di memoria al quale è associata la nostra connessione. In PHP questo indirizzo di memoria viene generalmente registrato all’interno di una variabile che viene usata ogni qualvolta si vogliono effettuare query sul database.
Il metodo exec_query, presente nella nostra classe infatti necessita (essendo basato sul metodo PHP ibase_query) di due parametri : l’handle del database e la stringa sql da eseguire.
Per le transazioni, il concetto è lo stesso. Ad ogni Transazione avviata corrisponde un handle, tutte le operazioni che si vorranno effettuare all’interno di questa dovranno far riferimento al suo handle specifico.
Per comodità definiremo un solo metodo per la gestione di tutte e tre le operazioni che in base ad un parametro definito, avvierà una Transazione, la completerà con una COMMIT o la annullerrà con una ROLLBACK.
Le funzioni che PHP mette a disposizione in merito all’argomento sono tre :

• ibase_trans : richiede in input gli argomenti della Transazione (vedi Riquadro 2) e l’handle del database selezionato, mentre restituisce in output l’handle della transazione.
• ibase_commit : dato in input l’handle della Transazione, effettua il commit e restituisce un valore booleano tra TRUE o FALSE a seconda di successo o insuccesso.
• ibase_rollback : dato in input l’handle della Transazione, effettua il rollback ed in output si comporta alla stessa maniera di ibase_commit.

Organizzando il nostro metodo, potremmo pensare di usare due parametri : il primo denominato $action che conterrà la descrizione dell’operazione da svolgere : “start” per l’avvio di una transazione e “commit” o “rollback” per il termine di questa in uno dei due modi. Il secondo parametro, $tr_id, lo considereremo un “jolly” nel senso che in caso di avvio della Transazione conterrà gli argomenti di questa (si veda sempre il Riquadro 2), mentre per commit o rollback conterrà l’handle della Transazione da terminare.
A questo punto mettendo in pratica quanto accennato, il codice del nostro metodo, potrebbe presentarsi come segue :

FUNCTION TRANSACTION ($action, $tr_id = NULL)
{
 switch ($action)
 {
  CASE "start" :
   $this->connect();
   RETURN ibase_trans($tr_id, $this->Link_ID);
   break;
  CASE "commit" :
   RETURN ibase_commit($tr_id);
   break;
  CASE "rollback" :
   RETURN ibase_rollback($tr_id);
   break;
  DEFAULT :
   RETURN NULL;
   break;
 }
}

Tramite il costrutto switch, decido che tipo di operazione effettuare. Il valore restituito dalla funzione dipenderà dall’operazione selezionata : in caso di “start” sarà l’handle della Transazione, mentre per gli altri due casi sarà TRUE in caso di successo o FALSE se l’operazione fallisce.
Se viene indicato in $action un valore diverso dai tre illustrati, la funzione restituisce NULL.
Unica nota è il fatto che per azione uguale a “start” prima di eseguire la funzione ibase_trans, richiamo la funzione $this->connect() vista nel primo articolo, per fare in modo che la proprietà $this->Link_ID della classe sia un database handle effettivo.

Dalla teoria alla pratica

Una volta aggiunto questo nuovo metodo alla nostra classe, possiamo procedere con la creazione di un esempio effettivo.
Struttureremo lo script in modo che presenti una checkbox che consenta di scegliere una fra tre opzioni : in un caso effettuerà un inserimento nella tabella PEOPLE e terminerà con una ROLLBACK, nell’altro con una COMMIT ed in più aggiungeremo la possibilità di cancellare il record eventualmente inserito (in modo da poter ripetere l’esempio più volte). Alla fine effettueremo una SELECT sulla tabella e ne visualizzeremo l’esito in modo da osservare i cambiamenti prodotti dalle nostre operazioni.
La checkbox porterà allo script la variabile $_POST[“selection”] che tramite il costrutto switch presente nello script, selezionerà l’operazione da svolgere.
Il risultato finale sarà quanto appare nel riquadro 3 : Lo script presenta argomenti trattati nei precenti articoli quali il passaggio di parametri alla query e la stampa in una tabella del result set di una query e che qui non verranno ulteriormente approfonditi, le parti da esaminare a fondo sono quelle in cui viene avviata la Transazione

   $tr_id = $db->transaction("start", IBASE_DEFAULT);

In questo modo assegnamo alla variabile $tr_id l’handle della transazione e proprio in funzione di questo, la query di inserimento verrà lanciata con questa variabile come parametro di handle :

   if (!$db->exec_query($tr_id, $ssql))

Se l’operazione ha successo, viene effettuata (a seconda della scelta) l’operazione di rollback o commit che terrà come riferimento sempre $tr_id come handle :

    $db->transaction("rollback", $tr_id);

o

    $db->transaction("commit", $tr_id);

Il risultato consentirà di visualizzare il comportamento del database nei due diversi casi : solo per COMMIT il record viene inserito, la modifica non avrà effetto per ROLLBACK.
Un’ulteriore ed interessante test potrebbe riguardare l’argomento passato alla Transazione in fase di avvio : se al posto di IBASE_DEFAULT indichiamo IBASE_READ e proviamo ad inserire il record, sia che effettuiamo una commit, sia che effettuiamo una rollback, otteniamo questo errore :
“attempted update during read-only transaction”, ciò conferma ancora di più l’importanza che ricoprono gli argomenti passati alla Transazione in fase di avvio.
Il risultato finale dopo una COMMIT appare in Figura 1.

Figura 1

Conclusioni

Bene. Abbiamo finito. La nostra classe ora consente di effettuare tutte le operazioni che generalmente si fanno su un database Firebird.
Inutile sottolineare un’ultima volta come l’implementazione di tutti i metodi presentati è puramente indicativa. Le potenzialità di un progetto simile sono pressoché infinite.

Riquadro 1 : Le transazioni di “default”

Proviamo a fare una veloce prova sul db di test /home/janet/dbtest.gdb (creato negli scorsi articoli) utilizzando l’utilissimo tool da linea di comando “isql” presente nella directory di installazione di Firebird (generalmente /opt/interbase/bin), effettuando un inserimento nella tabella PEOPLE seguito da un’istruzione di ROLLBACK :

[root@conflitto janet]# /opt/interbase/bin/isql
Use CONNECT or CREATE DATABASE to specify a database
SQL> CONNECT /home/janet/dbtest.gdb USER sysdba PASSWORD masterkey;
Database:  /home/janet/dbtest.gdb, User: sysdba
SQL> SELECT PCODE, PNAME, PSURNAME FROM PEOPLE;
 
       PCODE PNAME                          PSURNAME
============ ============================== ==============================
 
           0 Vito                           Corleone
           1 Michael                        Corleone
           2 Sonny                          Corleone
           3 Fredo                          Corleone
           4 Tom                            Hagen
           5 Peter                          Clemenza
           6 Kay                            Adams Corleone
 
SQL> INSERT INTO PEOPLE (PCODE, PNAME, PSURNAME) VALUES (6, 'Luca', 'Brasi');
SQL> SELECT PCODE, PNAME, PSURNAME FROM PEOPLE;
 
       PCODE PNAME                          PSURNAME
============ ============================== ==============================
 
           0 Vito                           Corleone
           1 Michael                        Corleone
           2 Sonny                          Corleone
           3 Fredo                          Corleone
           4 Tom                            Hagen
           5 Peter                          Clemenza
           6 Kay                            Adams Corleone
           6 Luca                           Brasi
 
SQL> ROLLBACK;
SQL> SELECT PCODE, PNAME, PSURNAME FROM PEOPLE;
 
       PCODE PNAME                          PSURNAME
============ ============================== ==============================
 
           0 Vito                           Corleone
           1 Michael                        Corleone
           2 Sonny                          Corleone
           3 Fredo                          Corleone
           4 Tom                            Hagen
           5 Peter                          Clemenza
           6 Kay                            Adams Corleone
 
SQL> QUIT;

All’inizio in tabella, effettuando la prima select, osserviamo come siano presenti solamente 6 record. Una volta effettuato l’inserimento, e rilanciata la select, ci accorgiamo di come il nuovo record inserito esista.
Forzando il ROLLBACK della Transazione, il record inserito sparisce, riportando il database allo stato inziale, come se noi non avessimo effettuato nessun tipo di operazione.
Questo dimostra come pur non avendo dichiarato esplicitamente l’avvio della Transazione, siamo in grado di controllarne il flusso tramite le istruzioni ROLLBACK e COMMIT.
Un’altra piccola nota : nel momento in cui viene effettuata una ROLLBACK o una COMMIT sulla Transazione di default, ne viene subito avviata una nuova, a sottolineare come ogni operazione sul database viene obbligatoriamente associata ad una Transazione. E’ questo lo stesso motivo per cui rimanendo nell’ambiente isql possiamo continuare a lanciare ROLLBACK o COMMIT a rotazione pur non effettuando nessun tipo di operazione : queste istruzioni chiuderanno la Transazione di default e Firebird sistematicamente ne creerà una nuova.

Riquadro 2 : Gli argomenti di ibase_trans

La scelta del parametro trans_args passabile alla funzione ibase_trans va effettuata tra questi valori predefiniti :

• IBASE_DEFAULT
• IBASE_READ
• IBASE_WRITE
• IBASE_COMMITTED
• IBASE_CONSISTENCY
• IBASE_CONCURRENCY
• IBASE_REC_VERSION
• IBASE_REC_NO_VERSION
• IBASE_WAIT
• IBASE_NOWAIT

Ciascuno di questi guida uno specifico comportamento della Transazione.
Purtroppo non esiste nemmeno sul sito ufficiale di PHP una spiegazione specifica su ciascuna singola voce, solo alcune (le più usate) sono abbastanza autoesplicative.
Indicando IBASE_DEFAULT ad esempio, si avvia una Transazione le cui proprietà sono quelle di default ossia access mode READ ONLY, lock resolution NO WAIT ed isolation level SNAPHOT.
Nell’attesa che il supporto di PHP da questo punto di vista migliori, è necessario sperimentare in ambiente di prova le opzioni che si vogliono utilizzare in modo da non incorrere in spiacevoli inconvenienti.

Riquadro 3 : Test con ROLLBACK e COMMIT

<html>
<body>
 
<?php  
 // Inclusione file ib_class 
 include("ib_class.inc"); 
 
 // Creazione classe Ibase_DB 
 $db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey"); 
 
 switch ($_POST["selection"]) {
  case "rollback" :  
   $tr_id = $db->transaction("start", IBASE_DEFAULT);
   echo ibase_errmsg();
   // Test Rollback
   $ssql = "INSERT INTO PEOPLE (pcode, pname, psurname) VALUES (?, ?, ?)";
   // Definisco i parametri
   $db->add_param(7);
   $db->add_param("Luca");
   $db->add_param("Brasi");   
   // Esecuzione query 
   if (!$db->exec_query($tr_id, $ssql)) 
    // C'e' un errore, lo visualizzo 
    echo "Si è verificato un errore : " . $db->Error;
   else
    $db->transaction("rollback", $tr_id);
   break;
 
  case "commit" :    
   $tr_id = $db->transaction("start", IBASE_DEFAULT);
   // Test Commit
   $ssql = "INSERT INTO PEOPLE (pcode, pname, psurname) VALUES (?, ?, ?)";  
   // Definisco i parametri
   $db->add_param(7);
   $db->add_param("Luca");
   $db->add_param("Brasi");   
   // Esecuzione query 
   if (!$db->exec_query($tr_id, $ssql)) 
    // C'e' un errore, lo visualizzo 
    echo "Si è verificato un errore : " . $db->Error;
   else
    $db->transaction("commit", $tr_id);
   break;
 
  case "delete": 
   // Cancello gli eventuali inserimenti
   $ssql = "DELETE FROM PEOPLE WHERE pcode = ?";  
   // Definisco i parametri
   $db->add_param(7);
   // Esecuzione query 
   if (!$db->exec_query(0, $ssql)) 
    // C'e' un errore, lo visualizzo 
    echo "Si è verificato un errore : " . $db->Error;
   break;
 
  default : break;
 } 
?>
 
<form action="<?=$_SERVER["PHP_SELF"];?>" method="post">
<input type="radio" name="selection" value="rollback">Inserisci ed effettua rollback (il record non viene inserito)
<br>
<input type="radio" name="selection" value="commit">Inserisci ed effettua commit (il record viene inserito)
<br>
<input type="radio" name="selection" value="delete">Cancella il record inserito
<br>
<input type="submit">
</form>
<p>Stato tabella :
 
<?php 
 $ssql = "SELECT a.PCODE, a.PNAME, a.PSURNAME FROM PEOPLE a ORDER BY a.PCODE"; 
 
 // Esecuzione query 
 if (!$db->exec_query(0, $ssql)) 
  // C'e' un errore, lo visualizzo 
  $db->display_error(1, $ssql); 
 else 
 {  
  echo "<table border="1">";
  // Creo le colonne della tabella
  while (list($colonna)=each($db->Fields_Info))
   echo "<th>" . $db->Fields_Info[$colonna]["alias"] . "</th>";
  // Creo le righe della tabella
  while ($db->next_record())
  {
   echo "<tr>";
   for ($fld = 0; $fld < $db->Num_Fields; $fld++)
    echo "<td>" . $db->Record[$db->Fields_Info[$fld]["alias"]] . "</td>";
   echo "</tr>";
  }
  echo "</table>";
 }
?>
 
</body> 
</html>

Allegati

Il file relativo alla classe a questo indirizzo : ib_class.inc.

La serie comprende questi articoli :

Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base
Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB
Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Dicembre 2004/Gennaio 2005.

Nello scorso articolo abbiamo iniziato a costruire una classe PHP per l’accesso ad un database Firebird. Sulla base di proprietà e metodi specifici abbiamo inziato ad effettuare query ed a navigare nei resultset di queste.
Quello che ci apprestiamo a fare ora è entrare nello specifico, costruendo metodi che ci permettano di gestire un tipo di campo particolare denominato BLOB.
Quanto segue si basa totalmente sulla classe presentata e costruita nello scorso articolo, senza quella base i nuovi metodi implementati non hanno senso.

Panoramica sui campi BLOB

In genere quando si definisce un campo in una tabella bisogna sapere a priori quale dovrà essere la sua dimensione massima. Molte volte però non è possibile stabilire a priori quanti dati dovrà contenere un campo, basti pensare alle note di un’ordine : come si può stabilire quanto un cliente scriverà all’interno di queste ? La risposta si trova appunto nei campi BLOB.
Un campo BLOB a differenza di tutte le altre tipologie definibili in un RDBMS ha la caratteristica di essere dimensionato dinamicamente, non viene definita cioè la grandezza del campo in fase di creazione.
In genere campi di questo tipo vengono utilizzati per gestire grandi quantità di dati di grandezza varibile : Immagini bitmap, file audio, file video, capitoli di libri e tantissime altre tipologie.
Proprio a causa di questa particolare attitudine, i campi BLOB non si possono gestire in maniera “comune” tramite operazioni di SELECT o INSERT, ma necessitano di misure particolari sia per la scrittura che per la lettura. Questo perchè non viene registrato direttamente il contenuto del campo all’interno della tabella, ma solo il suo identificativo, il BLOB_ID. I dati del BLOB vengono registrati in un’altra area del database, suddivisi in segmenti. Il BLOB_ID rappresenta l’indirizzo di partenza di questi segmenti.
Questo concetto è spiegato egregiamente in Figura 1.

Figura 1

Definire un campo BLOB

In Firebird la definizione di un campo BLOB all’interno di una tabella avviene in questo modo :

NOMECAMPO BLOB SUB_TYPE <tipo subtype> SEGMENT SIZE <grandezza>

Questo tipo di sintassi ci permette di dichiarare il nome del campo, il fatto che sia di tipo BLOB, il sottotipo (SUB_TYPE) e la grandezza dei sagmenti ad esso associati (SEGMENT SIZE).
SUB_TYPE rappresenta il sotto-tipo del campo, un valore che descrive la natura del dato in esso contenuto. In firebird ne esistono 9 tipi (da 0 a :

• 0
• 1 o TEXT
• 2 o BLR
• 3 o ACL
• 4 o RANGES
• 5 o SUMMARY
• 6 o FORMAT
• 7 o TRANSACTION_DESCRIPTION
• 8 o EXTERNAL_FILE_DESCRIPTOR :

Una spiegazione completa di ciascuno di questi particolari sottotipi la si può trovare a questo URL :
http://www.ibphoenix.com/a502.htm
per i nostri esempi noi adotteremo il subtipo TEXT, usato appunto per registrare e manipolare testo. Se non si è certi di quale tipo scegliere, si può non indicare nulla in quanto di default verrà considerato il sottotipo 0 che generalmente viene usato per dati binari o indefiniti.
SEGMENT SIZE rappresenta la grandezza massima che i segmenti del campo BLOB possono assumere. Il valore indicato può arrivare fino a 32767 bytes. Se non si indica il valore di grandezza del segmento, Firebird considera default SEGMENT SIZE 80.
Anche in questo caso sarebbe bene approfondire il concetto di SEGMENT SIZE sulla documentazione ufficiale di Interbase 6.0 nel pdf denominato DataDef.pdf, pagine relative ai campi BLOB (Le pagine dalla 76 in poi). Questa documentazione pur riferendosi ad una versione di Interbase passata (la prima ed unica OpenSource, 6.0) si adatta per i concetti esposti anche a Firebird. La sipuò trovare sul sito ufficiale di Firebird a questo indirizzo :
http://firebird.sourceforge.net/index.php?op=doc&id=userdoc
scaricare e consultare questa documentazione non è affatto un lavoro in utile, in particolare, relativamente ai campi BLOB, il capitolo 8 del libro “EMBEDDED SQL GUIDE”.
Seppur datata risulta in diverse occasioni assai preziosa. .

Prepararsi al lavoro

Nello scorso articolo avevamo già definito nel database di test una tabella con un campo BLOB :

CREATE TABLE PEOPLE (
    pcode    INTEGER NOT NULL,
    psurname VARCHAR(30) NOT NULL,
    pname    VARCHAR(30) NOT NULL,
    pquote   BLOB SUB_TYPE TEXT SEGMENT SIZE 240,   
    PRIMARY KEY (pcode)
);

La riga che a noi interessa è chiaramente quella contenente la dichiarazione del campo BLOB :

    pquote   BLOB SUB_TYPE TEXT SEGMENT SIZE 240,

Questa segnala a Firebird di creare un campo BLOB di sottotipo TEXT (quello che ci interessa memorizzare sono frasi “memorabili”, quindi essenzialmente testo) con segmenti di 240 bytes.
Questo campo ci permetterà di sperimentare le funzioni PHP per la gestione dei BLOB in Firebird.

Utilizzare i campi BLOB in PHP

Ciò che ci interessa implementare nella nostra classe PHP relativamente ai campi BLOB, sono le due operazioni fondamentali : lettura e scrittura.
Come già accennato precedentemente, per reperire un campo BLOB da una tabella non è sufficente effettuare una SELECT su questo e scriverne il contenuto in output semplicemente con una echo, come se si trattasse di un campo qualsiasi (ad esempio VARCHAR).
Se si dovesse procedere in questa maniera, non si riceverebbe alcun errore dal compilatore PHP, ma a video non apparirebbe il testo contenuto nel BLOB, bensì il suo ID, il quale apparendo in forma binaria risulterebbe del tutto incomprensibile.
Quindi procedendo correttamente i passi da svolgere per reperire il contenuto di un campo BLOB diventano i seguenti :

• Ricavare tramite SELECT il BLOB_ID del campo interessato;
• Aprire l’area di memoria del database identificata dal BLOB_ID;
• Reperire il contenuto del BLOB da quest’area per elaborarlo secondo le nostre esigenze;
• Chiudere l’area di memoria in questione.

Lo stesso concetto va applicato (anche se in maniera opposta) all’inserimento, i cui passi possono essere rappresentati come segue :

• Creare un’area di memoria nel database;
• Inserire in questa i valori relativi al contenuto (Testo o dati binari relativi ad immagini, video etc.);
• Registrare l’ID di quest’area di memoria nel campo BLOB della tabella;
• Chiudere l’area di memoria.

Per effettuare queste due serie di operazioni creeremo due metodi dal nome autoesplicativo : blob_field_in e blob_field_out.

PHP offre le funzioni di gestione dei campi BLOB in Interbase/Firebird, ma purtroppo sul sito ufficiale queste non sono documentate, poco male se si pensa che fino a pocotempo fa non erano nemmeno menzionate !
Un elenco completo delle funzioni disponibili lo si trova qui :
http://it2.php.net/manual/it/ref.ibase.php

Reperire valori da un campo BLOB

Dettati i presupposti possiamo inziare a creare un metodo che visualizzi il contenuto di un campo BLOB ricavato dal resultset di una query.
I parametri di cui il nostro metodo avrà bisogno saranno sicuramente il nome del campo interessato ed il formato di uscita dei dati, in modo da poter effettuare una pre-elaborazione dell’output e velocizzare i tempi di lavorazione.
Partendo dal presupposto che tramite il metodo exec_query (illustrato nel precedente articolo) abbiamo nell’array Record della nostra classe una riga del resultset della query effettuata, possiamo iniziare a concentrarci sui metodi PHP :
Per prima cosa è necessario reperire il BLOB_ID del nostro campo, la prima funzione che viene in nostro aiuto è ibase_blob_open : a questa va passato semplicemente il valore binario ricavato dalla query per farsi restituire il BLOB_ID relativo. Ora che conosciamo qual’è l’indirizzo di memoria dei dati che ci interessano, possiamo iniziare a reperirli tramite la funzione ibase_blob_get. A questa è necessario passare chiaramente il BLOB_ID ed in più la lunghezza in byte di quanti dati si vogliono reperire. La funzione restituirà tanti byte quanti ne sono stati richiesti fino a che non arriverà alla fine del campo, momento in cui il valore restituito diventerà FALSE.
Essendo il valore BLOB diviso in segmenti e non sapendo a priori la grandezza di questi, per effettuare un reperimento preciso useremo un comodo espediente : generiamo un numero casuale tramite la funzione rand e utilizziamo come lunghezza di byte il resto della divisione tra questo numero e 1024. Questo numero non potrà mai superare 1024, di conseguenza ci consentirà di reperire aree dati minori di 1024 bytes (1 Kb).
Seppur questo step possa sembrare superfluo (si potrebbe passare un valore fisso inferiore a 1024 sempre e comunque) è necessario e fondamentale per non sovraccaricare la memoria durante le operazioni di reperimento di grosse moli di dati da campi BLOB…Provare per credere !
Accodando i vari “pezzi” del nostro BLOB in una variabile potremmo finalmente avere in locale i dati che ci interessano ed operare su di essi per emetterli a seconda del formato d’uscita richiesto.
Una volta che quanto ci interessa si trova in una variabile locale, possiamo chiudere il BLOB attraverso la funzione ibase_blob_close alla quale va passato solo il BLOB_ID interessato.
I formati d’uscita potrebbero essere 3 : restituire il dato così come lo si riceve, restituire il dato con i caratteri speciali html convertiti in “escape sequences” per prevenire l’esecuzione di codice html o anche javascript maligno ed infine restituire il dato formattato per l’html (quindi con gli “accapo” trasformati in tag
), ma sempre con il discorso sicurezza applicato ai caratteri speciali html.
In conclusione il nostro metodo potrebbe presentarsi così :

function blob_field_out($field_name, $html)
{
 $blob_text = "";
 if ($this->Record[$field_name])
 {
  $blob_id = ibase_blob_open($this->Record[$field_name]);
  while ($piece = ibase_blob_get ($blob_id, rand() % 1024))
   $blob_text .= $piece;
  ibase_blob_close($blob_id);
  switch ($html) 
  {
   case "s" : break;
   case 0 || NULL || FALSE : $blob_text = htmlspecialchars($blob_text); break;
   default : $blob_text = nl2br(htmlspecialchars($blob_text)); break;
  }
 }
 return $blob_text;
}

Tutta la funzione dipende comunque dal fatto che $this->Record[$field_name] sia valorizzato, in caso contrario il valore restituito sarà una stringa vuota.
Il ciclo while serve per accodare i valori reperiti dal campo BLOB all’interno della variabile $blob_text e fino a che verrà assegnato un valore a $piece, $blob_text continuerà ad incrementarsi.
Il costrutto switch ci consente invece di selezionare il tipo di formato output : passando quindi “s” come secondo parametro al nostro metodo, considereremo il contenuto del BLOB affidabile e così come ci viene restituito, se invece questo non sarà valorizzato (0, NULL o FALSE) restituiremo il tutto “corretto” da eventuali entità html (la funzione htmlspecialchars non fa altro che questo), mentre se il parametro $html un valore qualsiasi diverso da questi oltre ad effettuare un controllo sulle entità html convertiremo anche i caratteri “n” o newline in accapo html ossia “<br>”.

Inserire valori in un campo BLOB

Inserire dei valori BLOB all’interno di una tabella significa creare un’area di memoria all’interno del database, scrivere in questa i dati che ci interessano, registrare il BLOB_ID associato nella tabella interessata e chiudere l’area di memoria aperta.
Il nostro metodo dovrà richiedere in input due parametri : il primo è il database handle, che rappresenterà l’indirizzo relativo alla connessione sulla quale stiamo lavorando, il secondo conterrà i dati da inserire nel campo BLOB.
Tramite il metodo PHP ibase_blob_create al quale va passato l’handle del nostro database reperiremo il BLOB_ID relativo ad una nuova area di memoria creata. Questo prezioso valore ci consentirà di inserire dati all’interno di quest’area tramite la funzione ibase_blob_add alla quale passeremo il BLOB_ID e la variabile contenente i dati da registrare. Infine faremo restituire al nostro metodo quanto riceveremo dalla funzione ibase_blob_close , ossia il BLOB_ID da registrare all’interno del campo della tabella.

function blob_field_in($dbh == NULL, $blob_text)
{
 if (!is_null($dbh) && is_resource($dbh))
  $this->Link_ID = $dbh;
 else
  $this->connect();
 
 $blob_id = ibase_blob_create($this->Link_ID);
 ibase_blob_add($blob_id, $blob_text);
 return ibase_blob_close($blob_id);
}

Se $dbh è valorizzato (non deve essere nullo e deve essere una risorsa), allora verrà usato questo handle per svolgere le operazioni, in caso contrario verrà richiamata la funzione connect.

Dalla teoria alla pratica

Una volta aggiunti questi due nuovi metodi alla nostra classe, possiamo procedere con la creazione di un esempio effettivo di inserimento di un record contenente un BLOB e la visualizzazione di questo.
Il codice contenuto nel Riquadro 1 riassume tutti i concetti esposti sinora.
Si parte con l’inclusione del file classe, la creazione di questa mediante il suo costruttore, e si inserisce tramite i parametri il nuovo record all’interno della tabella.
Particolare attenzione va posta alla riga

 $db->add_param($db->blob_field_in(0, $blob));

che aggiunge alla lista dei parametri anche il BLOB_ID ricavato dalla funzione blob_field_in che ci siamo costruiti, a questa vengono passati due parametri : 0 che rappresenta una connessione vuota ed obbliga quindi la funzione a stabilirne una nuova e $blob ossia la variabile che contiene il testo (con accapo) da inserire nel nostro BLOB.
Una volta eseguito con successo l’inserimento vengono proposti i due tipi di visualizzazione del risultato : nel primo il campo viene presentato così come è estratto dalla tabella, e come si può vedere dalla Figura 2, ciò che appare è assolutamente incomprensibile, nel secondo grazie alla riga

    echo "<td>" . $db->blob_field_out("PQUOTE", 1) . "</td>";

Viene visualizzato il risultato corretto (Figura 3), ossia quanto restituito dalla funzione blob_field_out, alla quale abbiamo passato il nome del campo interessato “PQUOTE” e 1 per indicare di convertire gli accapo in “<br>”.

Figura 2

Figura 3

Conclusioni

Ancora una volta ci tengo ad indicare come l’implementazione di tutti i metodi presentati è puramente indicativa. Si può fare tutto e più di tutto con questi strumenti che l’OpenSource ci mette a disposizione, questa è solo una delle tante vie.
In questo secondo articolo abbiamo cercato di capire il concetto di BLOB e di implementare metodi che ne consentano l’utilizzo, nel prossimo parleremo di transazioni, cercando anche in questo caso di creare metodi specifici che ci consentano di lavorare al meglio spremendo Firebird fino all’ultimo bit.

Riquadro 1 : Inserimento di un campo BLOB, visualizzazione scorretta e corretta

<html>
<body>
<?php
 // Inclusione file ib_class
 include("ib_class.inc");
 
 // Creazione classe db
 $db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey");
 
 // Inserimento BLOB
 
 // Stringa sql
 $ssql = "INSERT INTO PEOPLE (PCODE, PNAME, PSURNAME, PQUOTE)  VALUES (?, ?, ?, ?)";
 
 // Definizione variabile BLOB (con caratteri accapo)
 $blob = "It made me think of what you once told me:n"In five years the Corleone family will be completely legitimate."n
That was seven years ago.";
 
 // Passaggio parametri
 $db->add_param(6);
 $db->add_param("Kay");
 $db->add_param("Adams Corleone");
 $db->add_param($db->blob_field_in(0, $blob));
 
 // Esecuzione query
 if (!$db->exec_query(0, $ssql))
  // C'e' un errore, lo visualizzo
  echo "Si è verificato un errore : " . $db->Error;
 else
 {
  echo "Inserimento blob completato con successo !<p>";
 
  // Stringa sql
  $ssql = "SELECT a.PNAME, a.PQUOTE FROM PEOPLE a";
 
  // Visualizzazione senza utilizzo di blob_field_out
  echo "<p><i>Senza <b>blob_field_out</b></i><br>";
 
  // Esecuzione query
  if (!$db->exec_query(0, $ssql))
   // C'e' un errore, lo visualizzo
   echo "Si è verificato un errore : " . $db->Error;
  else
  {
   echo "<table border="1">n";
   echo "<th>Nome</th><th>Frase memorabile</th>n";
 
   // Creo le righe della tabella
   while ($db->next_record())
   {
    echo "<tr>";
    echo "<td>" . $db->Record["PNAME"] . "</td>";
    echo "<td>" . $db->Record["PQUOTE"] . "</td>";
    echo "</tr>n";
   }
   echo "</table>";
  }
 
  // Visualizzazione con blob_field_out
  echo "<p>Con <i><b>blob_field_out</b></i><br>";
 
  // Esecuzione query
  if (!$db->exec_query(0, $ssql))
   // C'e' un errore, lo visualizzo
   echo "Si è verificato un errore : " . $db->Error;
  else
  {
   echo "<table border="1">n";
   echo "<th>Nome</th><th>Frase memorabile</th>n";
 
   // Creo le righe della tabella
   while ($db->next_record())
   {
    echo "<tr>";
    echo "<td>" . $db->Record["PNAME"] . "</td>";
    echo "<td>" . $db->blob_field_out("PQUOTE", 1) . "</td>";
    echo "</tr>n";
   }
   echo "</table>";
  }
 }
?>
</body>
</html>

Allegati

Il file relativo alla classe a questo indirizzo : ib_class.inc.

La serie comprende questi articoli :

Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base
Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB
Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Novembre 2004.

Nell’esteso panorama degli RDBMS (Relational Database Management System) si sta pian piano ritagliando una fetta di mercato un progetto giovane, ma già molto maturo : Firebird.
Nato da una costola del più famoso Interbase della Borland, FireBird rappresenta un’ottimo punto di partenza per quanti vogliono impementare soluzioni database stabili ed efficenti.
Cercheremo in questa serie di articoli di imparare ad accedere a questo motore per database da PHP, costruendo, sulla base della programmazione ad oggetti, una classe di accesso personalizzata che chiameremo ib_class.
L’ideale, per essere subito operativi, è che nel sistema su cui si lavorerà ci sia installato il motore per database Firebird (la versione attuale e consigliata è la 1.0.3), un webserver (per esempio Apache, 1.3.x o 2.x è indifferente) che supporti Php (4.3.x) e che lo stesso PHP sia compilato con supporto Interbase (e quindi Firebird).

Prima di iniziare

Quella che segue è una breve panoramica su ciò che è la programmazione ad oggetti, su ciò che sono le classi, e su come vengono implementate ed utilizzate in PHP. Essendo l’obiettivo primario di questo articolo creare una classe PHP specifica, se si desidera approfondire gli argomenti in questione si può far riferimento al testo “Object Oriented Programming – Guida completa” edito da Apogeo per quanto riguarda lo studio della programmazione ad oggetti, mentre all’indirizzo http://it.php.net/oop per trovare spiegazioni ed esempi inerenti la programmazione ad oggetti in PHP.
Inoltre non dimentichiamoci mai del buon vecchio google (www.google.com) per effettuare qualsiasi tipo di ricerca tecnica.

OOP : Object Oriented Programming.

I concetti di classe ed oggetto (o istanza) sono alla base della programmazione ad oggetti (OOP, Object Oriented Programming). Una classe rappresenta l’astrazione di un oggetto mentre un oggetto è istanza di una classe : Creare un oggetto significa istanziare una classe.
Una struttura dati è definita classe quando racchiude in se delle variabili (denominate proprietà o attributi) e le funzioni per la manipolazione di queste (denominate metodi).
E’ importante che la struttura dati di una classe sia trasparente per chi la utilizza : si opererà su questa solo tramite i metodi in essa definiti, quindi sarà necessario conoscere come questi operano e quale è la loro funzione, non come sono stati implementati. In questo modo si garantisce che la classe diventi fruibile non solo da chi l’ha costruita, bensì da tutti coloro che conoscono come questa funziona e cosa fa.

Panoramica sulle classi in PHP.

PHP è un linguaggio procedurale che però supporta il paradigma della programmazione orientata agli oggetti, proprio per questo possiede una serie di parole chiave necessarie ad implementare classi.
Una classe in PHP viene creata tramite la parola chiave class e nel corpo della sua dichiarazione si trovano tutte le variabili (proprietà) e le funzioni (metodi) che ne descrivono l’implementazione.
Le proprietà di una classe vengono dichiarate tramite la parola chiave var mentre per i metodi viene usata la parola chiave function.
Per poter accedere alle funzioni e alle variabili interne di una classe, viene usata la pseudo-variabile $this. Questo perchè, in fase di progettazione, non si conosce il nome con cui la classe verrà istanziata all’interno dei vari programmi. Questa pseudo-variabile può essere quindi letta come “questo oggetto”, this appunto.
Per scorrere proprietà e metodi di un oggetto viene usato l’operatore “->” che consente, un pò come succede nello scorrimento delle directory tramite l’operatore “/” di reperire un valore associato ad un percorso : se volessi accedere al file file.txt sotto la cartella /files dovrei far riferimento a questo così : /files/file.txt, negli oggetti la sintassi per accedere ai dati richiama questo concetto : $this->nomeproprietà per le proprietà e $this->nomemetodo() per i metodi.
E’ da notare come la variabile si chiami $this->nomeproprietà, e non $this->$nomeproprietà, pur essendo questa dichiarata come var $nomeproprietà : ciò accade perchè le variabili in PHP vanno scritte con un unico simbolo dollaro.
Come ultima cosa è necessario far notare che, al di fuori della classe stessa, non è mai buona norma assegnare dei valori alle prioprietà di un oggetto, è molto meglio creare dei metodi che effettuino questi assegnamenti.
In PHP 5 è stato introdotto un sistema per evitare che le proprietà di un oggetto vengano modificate all’esterno di questo : dichiarando una variabile con la parola chiave private anzichè var.
Visto che implementeremo la nostra classe con la versione 4 di PHP, per il momento consideriamo quanto detto solo a livello teorico, cercando di non assegnare direttamente i valori alle proprietà.

Il costruttore, questo sconosciuto

Se tra i metodi dichiarati all’interno di una classe ne esiste uno con il nome uguale a questa, esso viene chiamato costruttore. Il costruttore viene invocato ogni volta che un’istanza della classe viene creata ed ha il compito di inizializzare le proprietà del nucoo oggetto. In PHP ciò avviene tramite la parola chiave new :
$nomeoggetto = new nomeclasse();
Se non esiste un costruttore, new istanzierà solamente la classe e sarà necessario che ogni parametro abbia dei valori di default.
Una volta creato l’oggetto, le proprietà di questo saranno accessibili in questo modo $nomeoggetto->nomeproprietà ed i metodi con $nomeoggetto->nomemetodo()
Non è obbligatorio avere un costruttore all’interno di una classe, ma questo metodo è talmente utile da non poterne fare a meno.
Per creare una classe che si rispetti quindi, si fa presto a capire come il primo metodo da implementare sia il costruttore.

Prepariamoci al lavoro

Ora che abbiamo introdotto tutti gli argomenti che tratteremo nel corso dell’articolo, siamo pronti per iniziare a lavorare.
Si può partire analizzando quali dovranno essere le funzionalità della nostra classe in base alle operazioni che dovrà svolgere : essendo una classe per l’accesso ad un database, sicuramente dovrà consentirci di stabilire una connessione, di effettuare query sulle tabelle e di navigare all’interno dei risultati delle nostre interrogazioni. E questo solo per cominciare.
E’ facile intuire come ad ogni funzionalità indicata, dovrà corrispondere un metodo.
Ciascuno di questi metodi dovrà basarsi sulle funzioni che PHP mette a disposizione per l’accesso ad Interbase/Firebird. Un elenco completo di queste funzioni lo si può trovare sul sito ufficiale di PHP, all’indirizzo http://it.php.net/manual/it/ref.ibase.php.
Quello che dovremo fare, per iniziare, sarà realizzare quattro metodi base :
Un metodo che consenta a chi opera con la classe di istanziarla : dovremo creare cioè il costruttore, partendo dal presupposto che questo metodo dovrà inizializzare le proprietà dell’oggetto ed avere lo stesso nome della classe.
Un metodo che permetta di connettersi ad un database Firebird basato sulla funzione ibase_connect;
Un metodo che consenta di effettuare delle query. La funzione che ci verrà in aiuto a questo punto sarà ibase_query;
Un ultimo metodo che permetta di operare sui resultset delle query, di scorrere cioè all’interno dei risultati in modo da poterli presentare nei nostri programmi;
E’ chiaro che questi sono i metodi base, nella stesura di questi necessiteremo di crearne degli altri “minori”, sino ad ottenere una classe pronta per essere usata negli accessi a database Interbase/Firebird.
Per concludere, cercheremo di sviluppare un esempio che acceda ad un database di test (la cui creazione è illustrata nel riquadro1) e che sfrutti tutti i metodi sinora illustrati.
Bene, pronti ? Via !

Creiamo il file

Partendo dal presupposto che la classe si chiamerà ib_class creiamo un file denominato ib_class.inc che contenga l’intestazione della nostra classe insieme alle prime proprietà essenziali : il nome host, che identifica appunto l’Host presso il quale “alloggia” il nostro db, il percorso (path) del database insieme allo username ed alla password di accesso, il Set di caratteri, il numero di buffers ed il dialetto sql usato dal server :

<?php
 
class ib_class {
 
var $Host          = "";      // Host (anche macchina remota)
var $Database      = "";      // Database (file con path)
var $User          = "";      // Utente
var $Password      = "";      // Password
var $Charset       = "";      // Set di caratteri
var $Buffers       = 0;       // Numero di buffers
var $Dialect       = 3;       // Dialetto SQL
 
};
 
?>

Quanto sopra può essere considerato come la vera base della nostra classe. Queste proprietà non a caso rappresentano i dati da passare alla funzione ibase_connect per effettuare la connessione al database che vedremo più avanti.
Ora si può procedere con la creazione di tutti gli altri metodi (e proprietà) specifici, il risultato finale sarà quanto appare nel file ib_class.inc contenuto nel CD, ma chiaramente procedere passo per passo aiuterà a capire meglio i concetti.

Istanziare la classe tramite il costruttore

Il nostro costruttore non dovrà fare altro che assegnare i valori che gli vengono passati dal chiamante (tramite la funzione new) alle proprietà del nostro oggetto.
Il metodo dovrà dichiarare i parametri che gli devono essere passati in input (che rispecchiano le proprietà sino ad ora dichiarate della nostra classe) e tramite l’ausilio della pseudo-variabile $this effettuare dei semplici assegnamenti.
Ecco come potrebbe apparire :

function ib_class ($Host, $Database, $Charset, $Buffers, $Dialect, $User, $Password)
{
 $this->Host = $Host;
 $this->Database = $Database;
 $this->Charset = $Charset;
 $this->Buffers = $Buffers;
 $this->Dialect = $Dialect;
 $this->User = $User;
 $this->Password = $Password;
}

Un esempio di come si potrà creare un istanza del nostro oggetto in uno script è quello che segue :

$db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey");

In questo modo, viene istanziata la classe ib_class nella variabile $db. Essa verrà inizializzata con i valori relativi al database di test che abbiamo creato seguendo quanto spiegato nel riquado 1. L’istanza della classe (il nostro oggetto) sarà da qui in avanti rappresentata dalla variabile $db.
Piccola considerazione : è facile capire come, dichiarando $db come variabile di sessione in questo modo :

$_SESSION[“db”] = $db;

non avremo bisogno ogni qualvolta ci servirà il nostro oggetto, di reistanziare la classe script per script. Potremo garantire così, tramite la propagazione delle sessioni, di avere in ogni script il nostro oggetto istanziato correttamente. Interessante no ?

Connettersi ad un database Firebird

Ogni volta che si stabilisce una connessione con Firebird (ed in genere con tutti gli RDBMS) a questa viene assegnato un’indirizzo di memoria, il suo handle. Tutte le iterazioni con il database (query, transazioni etc.) andranno effettuate utilizzando un handle specifico.
Quello che a noi interessa ottenere è il valore relativo al link di una connessione e registrarlo nel nostro oggetto in una nuova proprietà, denominata $this->Link_ID.
La funzione PHP che consente di stabilire una connessione con un database Firebird è ibase_connect : Questa funzione necessita in input dei dati relativi al database (altro non sono che le proprietà che abbiamo già dichiarato del nostro oggetto) ed in caso di successo restituisce l’handle della connessione.
Il metodo che andremo a dichiarare semplicemente eseguirà la funzione ibase_connect con i parametri del nostro oggetto e assegnerà l’handle restituito da questa funzione alla proprietà Link_ID.
Il valore restituito dal metodo sarà vero o falso, a seconda dell’esito della funzione ibase_errmsg che a sua volta restitusce (se esiste) il testo del messaggio di errore.
A livello di codice, il nostro metodo sarà così strutturato :

function connect()
{
 $this->Link_ID = @ibase_connect(
  $this->Host . ":" .
  $this->Database,
  $this->User,
  $this->Password,
  $this->Charset,
  $this->Buffers,
  $this->Dialect,
  $this->Role);
 // Se c'è errore allora metto il messaggio in Error e ritorno FALSE
 $this->Error = ibase_errmsg();
 return ibase_errmsg() ? FALSE : TRUE;
}

ibase_connect automaticamente controlla se esiste già un link oppure ne va creato uno nuovo e lo restituisce in output. In questi termini il nostro metodo potrà essere invocato più volte di fila senza che necessariamente stabilisca per ogni esecuzione una nuova connessione. Come si può intuire, questa funzionalità favorisce il basso traffico di rete (e quindi la maggiore velocità).
Da notare il carattere “@” che precede la chiamata alla funzione ibase_connect. Questo indica al motore PHP di non visualizzare errori o warnings in uscita dalla funzione. Ciò è molto utile se si personalizza la gestione degli errori, come abbiamo fatto noi, assegnando alla nuova proprietà $this->Error del nostro oggetto il valore di uscita della funzione ibase_errmsg. In questo modo potremo decidere quando e come far apparire gli eventuali messaggi di errore, senza generare immotivati timori negli utilizzatori dei nostri programmi

Effettuare delle query

Il metodo per l’esecuzione delle query diverrà essenziale per qualsiasi operazione ci troveremo a fare. Proprio per questo è necessario porre particolare cura nella sua implementazione.
La funzione PHP da tenere come riferimento è ibase_query. Per essere eseguita con successo, questa necessita dell’handle del database e di una valida stringa sql. Se ha successo e vi sono righe nel risultato (come si ha ad esempio con le query SELECT), restituisce un identificatore di risorsa, mentre se ha successo ma non ci sono righe risultato, restituisce semplicemente TRUE. In caso di fallimento il valore restituito sarà FALSE.
Il concetto di identificatore di risorsa, non si scosta molto da quello di handle : esso rappresenta infatti la parte di memoria riservata al resultset (l’insieme dei valori risultanti da una query di tipo SELECT) generato da una query.
Il nostro metodo deve eseguire queste operazioni :
Controllo esistenza di una connessione
Esecuzione della query
Controllo esistenza di un resultset e settaggio della nuova proprietà $this->Query_ID con il valore dell’identificatore di risorsa.
Restituzione del valore “vero” o “falso” a seconda dell’esito della query.
I parametri che il nostro metodo riceverà in input saranno due : il database handle, $dbh e la stringa sql da eseguire, $query_string. E’ da notare come nella dichiarazione della variabile $dbh venga ad essa assegnato un valore di default, ciò risulterà molto utile nella verifica della validità che viene effettuata all’inizio della funzione.
Se $dbh è valorizzato (non deve essere nullo e deve essere una risorsa), allora verrà usato questo handle per svolgere le operazioni, in caso contrario verrà richiamata la funzione connect. Passare un handle diverso da quello di default, tornerà utile quando in futuro parleremo di transazioni.
Esaminiamo insieme il codice di questo metodo :

function exec_query($dbh = NULL, $query_string)
{
 if (!is_null($dbh) && is_resource($dbh))
  $this->Link_ID = $dbh;
 else
  $this->connect();
 
 array_unshift($this->Query_Params, $this->Link_ID, $query_string);
 $this->Query_ID = @call_user_func_array("ibase_query", $this->Query_Params);
 
 if ($this->Query_ID)
 {
  $this->Row = -1;
  // La query e' andata a buon fine, setto la variabile Query_Sql della classe ...
  $this->Query_Sql = $query_string;
  // ...Azzero i parametri...
  $this->Query_Params = array();
  // ...E se non e' una operazione di modifica creo i metadata
  if ((substr(strtoupper($query_string), 0, 6) != "INSERT")&&
      (substr(strtoupper($query_string), 0, 6) != "UPDATE")&&
      (substr(strtoupper($query_string), 0, 6) != "CREATE")&&
      (substr(strtoupper($query_string), 0, 6) != "DELETE"))
   $this->metadata();
 }
 
 // Se c'è errore allora metto il messaggio in Error e ritorno FALSE
 $this->Error = ibase_errmsg();
 return ibase_errmsg() ? FALSE : TRUE;
}

Dopo aver effettuato il controllo sul database handle già descritto, particolare attenzione va posta verso le due righe

 array_unshift($this->Query_Params, $this->Link_ID, $query_string);
 $this->Query_ID = @call_user_func_array("ibase_query", $this->Query_Params);

Queste fanno riferimento alla nuova proprietà $this->Query_Params del nostro oggetto, un array che contiene i parametri che la funzione ibase_queryrichiede in input.
array_unshift inserisce uno o più elementi all’inizio di un array, mentre call_user_func_array passa come parametri ad una funzione indicata i valori presenti in un array. Questo significa che se $this->Query_Params è vuota, ad ibase_query() saranno passati solamente due parametri (handle e stringa sql), mentre nel caso contrario tutti i valori presenti in $this->Query_Params verranno passati a ibase_query nell’ordine in cui sono presenti nell’array.
Per spiegare il funzionamento di queste due righe, consideriamo questa query che vuole estrarre tutti i record della tabella PEOPLE che abbiano PSURNAME uguale a “Corleone” :

$ssql = “SELECT a.* FROM PEOPLE WHERE a.PSURNAME = ?”;
ibase_query($dbh, $ssql, “Corleone”);

$ssql = “SELECT a.* FROM PEOPLE WHERE a.PSURNAME = 'Corleone'”;
ibase_query($dbh, $ssql);

function add_param($param)
{
 $this->Query_Params[] = $param;
}

$ssql = “SELECT a.* FROM PEOPLE WHERE a.PSURNAME <> ?”;
$db->add_param(“Corleone”);
$db->exec_query(0, $ssql);

function metadata()
{
 $c=0;
 while ($campo = ibase_field_info($this->Query_ID,$c))
 {
  $info[$c]["name"] = $campo["name"];
  $info[$c]["alias"] = $campo["alias"];
  $info[$c]["relation"] = $campo["relation"];
  $info[$c]["length"] = $campo["length"];
  $info[$c]["type"] = $campo["type"];
  $info[$c]["index"] = $c;
  $c++;
 }
 $this->Fields_Info=$info;
 $this->Num_Fields=ibase_num_fields($this->Query_ID);
 // L'array viene anche restituito
 return $info;
}

Il cui scopo è quello di creare l’array associativo $this->Fields_Info con le proprietà dei campi della tabella risulato attraverso la funzione ibase_field_info(), la quale, richiamata per ogni campo, restituisce un array con informazioni relative a questo nella forma name, alias, relation, length e type.
$this->metadata() assegna anche alla nuova proprietà Num_Fields dell’oggetto il risultato della funzione ibase_num_fields() che restituisce il numero di campi della tabella risultato.
Infine exec_query controlla che non vi siano errori nello stesso identico sistema di connect, restituendo TRUE o FALSE a seconda del valore restituito da ibase_errmsg().

Operare sui resultset delle query

Prima di addentrarci nel primo esempio effettivo di utilizzo della nostra classe è necessario capire come fare a muoversi all’interno di un resultset restituito da una query.
La funzione PHP che ci viene in aiuto in questo caso è ibase_fetch_row. Questa funzione necessita in input dell’identificatore di risorsa relativo ad una query eseguita e restituisce un array con struttura indicecampo->valore. Il primo passo da compiere quindi è creare una proprietà di tipo array nel nostro oggetto denominata Record che servirà a contenere l’associazione restituita da ibase_fetch_row.
Ma noi vogliamo di più.
Oltre a questa associazione ne vogliamo creare un’ulteriore di tipo nomecampo->valore, in questo modo non saremo costretti a ricordarci quale sia l’indice di un campo per conoscerne il valore, basterà sapere il nome di questo ed accederci tramite Record[“nomecampo”].
Ad esempio se il primo campo di un resultset sarà denominato CHIAVE avremo due modi per accedere al suo valore : tramite l’indice campo $db->Record[0] oppure tramite il nome campo $db->Record[“CHIAVE”].
Analizziamo nel dettaglio il nostro metodo :

function next_record()
{
 if ($this->Record = ibase_fetch_row($this->Query_ID))
 {
  $this->Row += 1;
  $stat = 1;
 }
 else
 {
  if ($this->Auto_Free)
   $this->free_result();
  $stat = 0;
 }
 //Assegnazione valori Array associativo Record[“nomecampo”] = valorecampo
 $flds = $this->Num_Fields;
 for ($fld = 0; $fld < $flds; $fld++)
  $this->Record[$this->Fields_Info[$fld]["alias"]] = $this->Record[$fld];
 //ritorno stat: 1=0K, 0=nessun record & effettuato il free se c'è auto_free
 return $stat;
}

La proprietà dell’oggetto Row (che rappresenta il numero di riga corrente) viene incrementata fino a che l’assegnazione $this->Record = ibase_fetch_row($this->Query_ID) produce esito positivo.
L’associazione Record[“nomecampo”]->valore, viene creata partendo dalla proprietà $this->Fields_Info[$fld]["alias"] che è stata valorizzata dal metodo $this->metadata() in exec_query();
Ciclando sul numero di campi del resultset ($this->Num_Fields), aggiunge un elemento all’array record che ha per chiave il nome del campo e per valore quello relativo all’indice di questo.
next_record restituirà 1 fino a che non si troverà sull’ultimo record, momento in cui la variabile $stat (e quindi il valore restituito dal metodo) sarà 0. A questo punto verrà effettuato un check anche sulla nuova proprietà $this->Auto_Free, se questa è valorizzata, allora verrà lanciato il metodo $this->free_result() :

function free_result()
{
 ibase_free_result($this->Query_ID);
 $this->Query_ID = 0;
}

Questo metodo funziona sulla base della funzione ibase_free_result, che libera la memoria allocata da un resultset.

Mettiamo in pratica

L’esempio contenuto nel riquadro 2 contiene tutti gli argomenti che abbiamo trattato sin’ora : Una volta incluso il file “ib_class.inc” contenente il codice della nostra classe si procede con la creazione di una sua istanza nella variabile $db.
La fase successiva prevede la dichiarazione della stringa contenente il codice SQL che vogliamo far eseguire. In questo caso si tratta di voler estrarre dalla tabella PEOPLE tutte le persone che hanno un cognome (PSURNAME) contenente la parola “Corleone” indipendentemente dalle maiuscole o minuscole.
A questo punto viene aggiunto il parametro stringa di confronto e viene eseguita la query.
Da notare come l’if sia impostato direttamente sull’esito della query. Se la query non va a buon fine, viene visualizzato il testo dell’errore mentre in caso di successo viene creata una tabella con i risultati visualizzati.
Prima verranno stampate con un ciclo while le colonne <th> della tabella utilizzando l’array $db->Fields_Info che è stato creato da $this->metadata in $db->exec_query, infine lo script ciclerà sulla funzione $db->next_record fino a che questa restituirà un valore effettivo (cioè fino a che non arriverà alla fine dell’elenco) visualizzando il valore di ciascun campo in una cella.
L’output effettivo di questo script non dovrebbe essere troppo diverso da quello presentato nella figura 1.

Figura 1

Conclusioni

Chiaramente l’implementazione di tutti i metodi dell’oggetto è puramente indicativa. Ciascuno di essi infatti può essere modificato ed ottimizzato in funzione delle proprie specifiche esigenze. Una personalizzazione mirata è alla base dello sviluppo di un buon progetto.
In questo primo articolo abbiamo realizzato la base per la nostra classe di accesso, nei successivi implementeremo nuovi metodi per renderla più completa possibile : introdurremo metodi specifici per la gestione dei campi Blob, delle transazioni e per tutte le varie tipologie di campi.

Riquadro 1 : Creazione ambiente di test

Prima di iniziare a fare i test con gli script PHP e la nostra classe e’ necessario creare un database di prova, sul quale poter combinare tutti i possibili danni di cui siamo capaci senza nuocere a nessuno…
Assumiamo come directory di lavoro /home/janet e creiamo un file denominato dbtest.sql con il nostro editor di testo preferito :

vi /home/janet/dbtest_create.sql

scrivendoci all’interno i dati per la creazione del nostro db :

SET SQL DIALECT 3;
 
CREATE DATABASE 'localhost:/home/janet/dbtest.gdb'  USER 'SYSDBA' PASSWORD 'masterkey';
 
CREATE TABLE PEOPLE (
    pcode    INTEGER NOT NULL,
    psurname VARCHAR(30) NOT NULL,
    pname    VARCHAR(30) NOT NULL,
    pquote   BLOB SUB_TYPE TEXT SEGMENT SIZE 240,   
    PRIMARY KEY (pcode)
);
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (0, 'Corleone', 'Vito', 'I''ll make him an offer he can''t refuse.');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (1, 'Corleone', 'Michael', 'Don''t ask me about my business, Kay.');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (2, 'Corleone', 'Sonny', 'Goddamn FBI don''t respect nothin''.');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (3, 'Corleone', 'Fredo', 'I''m smart and I want respect !');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (4, 'Hagen', 'Tom', 'Mr. Corleone never asks a second favor once he''s refused the first, understood ?');
 
INSERT INTO PEOPLE (pcode, psurname, pname, pquote) 
 VALUES (5, 'Clemenza', 'Peter', 'Mikey, why don''t you tell that nice girl you love her ?');
 
COMMIT;

Una volta scritto quanto sopra, salviamo il file e lanciamo questo comando come utente root :

/opt/interbase/bin/isql -i /home/janet/dbtest_create.sql

Se non riceviamo messaggi di errore, dovremmo trovarci nella directory /home/janet il nostro file dbtest.gdb pronto da usare.

Riquadro 2 : il primo script con la nostra classe

<html>
<body>
<?php 
 // Inclusione file ib_class 
 include("ib_class.inc"); 
 
 // Creazione classe db 
 $db = new ib_class("localhost", "/home/janet/dbtest.gdb", "", 0, 3, "SYSDBA", "masterkey"); 
 
 // Stringa sql
 $ssql = "SELECT a.PSURNAME, a.PNAME FROM PEOPLE a WHERE upper(a.PSURNAME) LIKE upper(?)"; 
 
 // Aggiungo il parametro
 
 $db->add_param("%Corleone%");
 
 // Esecuzione query 
 if (!$db->exec_query(0, $ssql)) 
  // C'e' un errore, lo visualizzo 
  echo "Si è verificato un errore : " . $db->Error; 
 else 
 { 
  echo "<table border="1">";
 
  // Creo le colonne della tabella
  while (list($colonna)=each($db->Fields_Info))
   echo "<th>" . $db->Fields_Info[$colonna]["alias"] . "</th>";
 
 
 
  // Creo le righe della tabella
  while ($db->next_record()) 
  {
   echo "<tr>";
   for ($fld = 0; $fld < $db->Num_Fields; $fld++)
    echo "<td>" . $db->Record[$fld] . "</td>";
   echo "</tr>";
  }
  echo "</table>";
 }  
?>
</body>
</html>

Allegati

Il file relativo alla classe a questo indirizzo : ib_class.inc.

La serie comprende questi articoli :

Una classe PHP per l’accesso a Firebird – Parte 1: costruzione della classe e implementazione dei metodi base
Una classe PHP per l’accesso a Firebird – Parte 2: Gestione dei campi BLOB
Una classe PHP per l’accesso a Firebird – Parte 3: Gestione delle Transazioni

Nota :

Questo articolo è originariamente apparso nell’edizione italiana di Linux Journal nel Ottobre 2004.