Come definito nella documentazione di PostgreSQL sui tipi di dato binario, il tipo di dato bytea permette la memorizzazione di stringhe binarie (vere e proprie sequenze di byte) di lunghezza variabile in un campo di una tabella. PostgreSQL fornisce le specifiche per la codifica di queste stringhe binarie, tuttavia i linguaggi di programmazione e le librerie di astrazione più comuni mettono a disposizione meccanismi automatici e trasparenti per la serializzazione/deserializzazione dei dati. PDO per PHP è uno di questi. Purtroppo, la documentazione sul tipo di dato bytea di PostgreSQL è molto scarsa e uno degli obiettivi di questo articolo è di dimostrare con un esempio quanto questo sia facile. Gli esempi forniti sono molto semplici e il loro scopo è puramente didattico. Non sono da utilizzare "così come sono" in un ambiente di produzione in quanto non sono gestiti gli errori e le eccezioni.

La tabella ‘documenti’

Supponiamo di avere una tabella chiamata documenti, così composta:

CREATE TABLE documenti (
id serial,
documento bytea
);

E supponiamo di volere memorizzare il contenuto compresso di una stringa di testo dentro il campo documento. In PHP è possibile comprimere il contenuto di una stringa con il comando gzencode. La funzione ritorna una stringa binaria che può essere memorizzata come oggetto binario in PostgreSQL.

// $docstr contiene la stringa originale (ad esempio un documento HTML)
// $gzdoc contiene la stringa binaria (il documento HTML compresso ad esempio)
$gzdoc = gzencode($docstr);

Inserimento di un campo bytea

Il primo passo consiste nella creazione della query preparata:

$stmt = $connection->prepare('INSERT INTO documenti (documento) VALUES (?)');

Il passo successivo è quello di informare PDO che il primo parametro della query preparata è un tipo di dato bytea e deve essere trattato come un dato binario. La costante PDO da utilizzare è PDO::PARAM_LOB.

$stmt->bindParam(1, $gzdoc, PDO::PARAM_LOB);

L’ultimo passo è l’esecuzione della query:

$stmt->execute();

Selezione di un campo bytea

Il modo migliore per recuperare il contenuto di un campo bytea è quello di associare una colonna a una variabile utilizzando bindColumn della classe PDOStatement. Il codice di esempio è fornito qui sotto:

// la variabile $id contiene l'ID del documento da recuperare
$stmt = $dbh->prepare('SELECT documento FROM documenti WHERE id = ?');
$stmt->bindParam(1, $id, PDO::PARAM_INT);
$stmt->execute(); // esegue la query
// Associa la prima colonna di risultato alla variabile locale
// $gzdoc che conterrà il valore del campo 'documento'
$stmt->bindColumn(1, $gzdoc);
$stmt->fetch(PDO::FETCH_BOUND);
// echo $gzdoc; // visualizza la stringa binaria
// echo gzdecode($gzdoc); // visualizza la stringa originale

Conclusioni

Questa breve guida ha esposto un piccolo esempio di inserimento e di selezione di dati binari in PostgreSQL memorizzati in campi bytea utilizzando PHP e PDO. Il tipo di dato bytea rappresenta una delle caratteristiche peculiari di Postgres nel trattamento di dati binari e semplifica notevolmente la gestione dei backup logici. In MySQL un tipo di dato simile è costituito dal MEDIUMBLOB. Se siete interessati a approfondire questo argomento, non esitate a contattarmi oppure a partecipare a uno dei corsi 2ndQuadrant su PHP.

PHP 5 mette a disposizione degli sviluppatori PDO, PHP Data Objects, una estensione molto potente per la connessione ai database utilizzando una interfaccia consistente, universale e leggera. L’accesso ai singoli database avviene sulla base di un driver PDO specifico (ad esempio esiste il driver PDO per PostgreSQL, come quello per MySQL, …).

In gergo tecnico, PDO fornisce un livello di astrazione all’accesso ai dati. A differenza di framework di astrazione dal database (ad esempio Pear MDB2 o l’obsoleto Pear DB), PDO accede al database utilizzando direttamente le funzioni native messe a disposizione dal driver specifico.

Al momento rappresenta sicuramente il miglior modo per accedere a un sistema di gestione di database con PHP.

Premesse

L’esempio utilizza PHP 5.3 su Mac OS X, installato con Mac Ports. E’ necessario installare PDO con il driver per PostgreSQL.

Si presuppone che si abbia una buona conoscenza di PostgreSQL, che si sia in grado di creare un utente, un database e una tabella.

Gli esempi sono stati testati su PostgreSQL 8.4.1, ma i concetti sono applicabili anche su versioni precedenti (si consiglia comunque di utilizzare almeno PostgreSQL 8.3 in produzione): il server PostgreSQL si presuppone installato sulla stessa macchina del PHP in ascolto sulla porta di default 5432.

Infine, vengono riportati soltanto alcuni snippet (pezzi) di codice, quelli pertinenti all’utilizzo di PDO con PostgreSQL: sarà premura del programmatore includerli all’interno delle proprie applicazioni.

Come utente postgres, creare l’utente pdo e il database pdo, eseguengo le seguenti istruzioni SQL tramite psql (si possono utilizzare anche altri prodotti per l’amministrazione di database PostgreSQL come PHPPgAdmin, pgAdmin III oppure l’alternativa commerciale Navicat):

CREATE USER pdo WITH ENCRYPTED PASSWORD 'pdo';
CREATE DATABASE pdo WITH OWNER pdo ENCODING 'UTF8';

Connettersi al database pdo come utente pdo e creare la tabella bands:

CREATE TABLE bands (
id SERIAL PRIMARY KEY,
band_name VARCHAR(256) NOT NULL
);

Connessione tramite PHP

Per connettersi con PHP tramite PDO al database di esempio, è necessario definire il Data Source Name (DSN). La sintassi in PostgreSQL prevede un prefisso pgsql: seguito da coppie variabile/valore per i seguenti possibili elementi:

• host: nome dell’host, indirizzo IP oppure directory per la socket locale Unix;
• port: porta del server PostgreSQL (di default 5432);
• dbname: nome del database;
• user: nome dell’utente per la connesione al database;
• password: relativa password;

Il DSN per l’esempio risulta pertanto essere:

pgsql:host=localhost port=5432 dbname=pdo user=pdo password=pdo

La connessione avviene tramite la creazione di un oggetto PDO, specificando un DSN:

$dsn = 'pgsql:host=localhost port=5432 dbname=pdo user=pdo password=pdo';
$connection = new PDO($dsn);

Il primo vantaggio dell’utilizzo di PDO che si evince subito è l’approccio Object Oriented. In caso di errore, il costruttore della classe PDO lancia una eccezione PDOException. Includere il codice all’interno di blocchi try/catch semplifica molto la gestione degli errori.

Per maggiori informazioni: Costruttore classe PDO.

Inserimento di record

PDO mette a disposizione il metodo prepare per la creazione delle query preparate (prepared statement). La funzione accetta una stringa (che può contenere dei parametri, solitamente identificati dal carattere ‘?’) e restituisce un oggetto di tipo PDOStatement.

In caso di utilizzo di parametri, questo possono essere associati a variabili locali, sgravando pertanto il programmatore dalle operazioni di escaping che spesso costituiscono fonte di problemi. Ciò è possibile utilizzando il metodo bindParam della classe PDOStatement.

$stmt = $connection->prepare('INSERT INTO bands (band_name) VALUES (?)');
// Inserisce la prima band
$band = 'Dave Matthews Band';
$stmt->bindParam(1, $band, PDO::PARAM_STR);
// 1: il primo parametro nella query preparata
// $band: la variabile che contiene il valore da passare alla
query come primo parametro
// PDO::PARAM_STR: informa PDO che la variabile band deve
essere inserita nel database come stringa
$stmt->execute();

Selezione di record

Come nel caso dell’inserimento, PDO mette a disposizione la funzione prepare per l’esecuzione di query preparate (la cosa è estremamente utile nel caso di parametri nella condizione WHERE della query SELECT).

Tuttavia, torneremo con maggior dettaglio su questo argomento quando tratteremo i bytea (per usare une semplificazione, i campi blob inline di PostgreSQL). In questa sede copriremo il semplice metodo query della classe PDO, con il seguente esempio:

$results = array();
$sql = 'SELECT* FROM bands';
foreach ($connection->query($sql) as $row) {
$results['id']= $row;
}

Conclusioni

Questa breve guida ha esposto un esempio di connessione a un database PostgreSQL utilizzando PDO e l’esecuzione di una istruzione INSERT e di una SELECT. L’esecuzione di istruzioni DELETE e UPDATE è molto semplice e può essere intuita facilmente. In uno dei prossimi articoli copriremo uno degli aspetti meno trattati dell’interfacciamento di PostgreSQL e PDO in PHP: l’inserimento e il recupero di campi di tipo bytea.

Se siete interessati a approfondire questo argomento, non esitate a contattarmi oppure a partecipare a uno dei corsi 2ndQuadrant su PHP.