Lavorare con il database in Drupal 7 – Lezione 3 – Query statiche (SELECT)

La forma più comune di query in Drupal è la query statica. Una query statica viene passata al database così com’è, senza modifiche da parte di Drupal. Solo le query di selezione (SELECT) possono essere statiche.

Le query statiche dovrebbero essere usate solo per operazioni molto semplici. Per query più complesse, dinamiche o modificabili a runtime, è preferibile usare le query dinamiche.

Un modo semplice per eseguire una query statica è il seguente:

<?php
$result = $conn->query("SELECT nid, title FROM {node}");
?>

Tuttavia, è preferibile utilizzare il wrapper procedurale:

<?php
$result = db_query("SELECT nid, title FROM {node}");
?>

Chiamare db_query() come sopra è equivalente a scrivere:

<?php
$result = Database::getConnection()->query("SELECT nid, title FROM {node}");
?>

Vediamo perché usare db_query() è migliore che richiamare direttamente l’oggetto Database.

db_query() accetta tre argomenti:

1. La stringa della query SQL (dove le tabelle devono essere racchiuse tra {} e i valori dinamici gestiti tramite segnaposti).
2. Un array di segnaposti (placeholders).
3. Un array opzionale di parametri di configurazione che controllano l’esecuzione della query.

Prefissi

Nelle query statiche, tutti i nomi delle tabelle devono essere racchiusi tra parentesi graffe {}. Questo consente a Drupal di aggiungere automaticamente un prefisso ai nomi delle tabelle. I prefissi sono utili, ad esempio, quando più siti Drupal condividono lo stesso database, distinguendo le tabelle con prefissi come “site1_” o “site2_”.

Segnaposti

I segnaposti vengono utilizzati per indicare dove verranno inseriti i valori all’interno della query. Separando la sintassi SQL dai valori forniti dall’utente, Drupal evita vulnerabilità come le SQL injection.

<?php
$result = db_query("SELECT nid, title FROM {node} WHERE created > :created", array(
  ':created' => REQUEST_TIME - 3600,
));
?>

Il codice sopra seleziona tutti i nodi creati nell’ultima ora. Il segnaposto :created viene sostituito dinamicamente con REQUEST_TIME - 3600, dove REQUEST_TIME rappresenta l’ora corrente di esecuzione.

È possibile usare più segnaposti nella stessa query, purché ciascuno abbia un nome univoco, anche se i valori sono identici.

L’array di segnaposti può essere dichiarato direttamente (come nell’esempio) o definito altrove e poi passato alla query. L’ordine non è importante. I segnaposti che iniziano con db_ sono riservati dal sistema e non devono essere usati manualmente.

È importante ricordare che i segnaposti non devono essere racchiusi tra virgolette nella query. Drupal gestisce automaticamente il tipo di dato (stringa o numero).

<?php
// ERRATO:
$result = db_query("SELECT nid, title FROM {node} WHERE type = ':type'", array(
  ':type' => 'page',
));

// CORRETTO:
$result = db_query("SELECT nid, title FROM {node} WHERE type = :type", array(
  ':type' => 'page',
));
?>

I segnaposti non devono essere usati per nomi di tabelle o colonne, ma solo per valori testuali o numerici.

Array di segnaposti

Il livello Database di Drupal offre una comoda funzionalità: se un segnaposto contiene un array di valori, Drupal lo convertirà automaticamente in un elenco separato da virgole. Ciò significa che non è necessario contare manualmente i segnaposti. Ad esempio:

<?php
db_query("SELECT * FROM {node} WHERE nid IN (:nids)", array(':nids' => array(13, 42, 144)));

// Drupal lo tradurrà automaticamente in:
db_query("SELECT * FROM {node} WHERE nid IN (:nids_1, :nids_2, :nids_3)", array(
  ':nids_1' => 13,
  ':nids_2' => 42,
  ':nids_3' => 144,
));

// Che a sua volta equivale a:
db_query("SELECT * FROM {node} WHERE nid IN (13, 42, 144)");
?>

Parametri della query

Il terzo parametro di db_query() è un array di configurazione che specifica come Drupal deve gestire la query. Solitamente si usano solo due chiavi principali:

• target – Specifica dove deve essere eseguita la query. Se non è definito, il valore predefinito è “default”. Se impostato su “slave”, la query sarà eseguita su un database secondario (replica), se disponibile.
• fetch – Specifica il formato dei dati restituiti dal database. I valori possibili sono:
  • PDO::FETCH_OBJ – Restituisce ogni riga come oggetto (default).
  • PDO::FETCH_ASSOC – Restituisce ogni riga come array associativo.
  • PDO::FETCH_NUM – Restituisce ogni riga come array numerico.
  • PDO::FETCH_BOTH – Restituisce ogni riga come array sia associativo che numerico.
  • Una stringa contenente il nome di una classe – ogni riga verrà restituita come oggetto di quella classe.

Ulteriori informazioni sono disponibili nella documentazione ufficiale PHP: PDOStatement::fetch().

Ecco un esempio di query eseguita su un database “slave”, con risultati restituiti come array associativo:

<?php
$result = db_query("SELECT nid, title FROM {node}", array(), array(
  'target' => 'slave',
  'fetch' => PDO::FETCH_ASSOC,
));
?>