Lavorare con il database in Drupal 7 – Lezione 8 – Query di inserimento (INSERT INTO)

14/10/2025, by Ivan

Le query di inserimento devono sempre essere costruite utilizzando il costruttore di query. Alcuni database richiedono gestori speciali per i campi LOB (Large Object, come TEXT in MySQL) e BLOB (Binary Large Object), quindi è necessario un livello di astrazione per consentire ai driver di database di implementare tali gestori specifici.

Le query di inserimento iniziano con la funzione db_insert():

<?php
$query = db_insert('node', $options);
?>

Questa query di inserimento crea un oggetto di query che inserisce uno o più record nella tabella node. Nota che non è necessario racchiudere il nome della tabella tra parentesi graffe — il costruttore di query lo fa automaticamente.

Le query di inserimento utilizzano il Fluent API, il che significa che tutti i metodi (incluso execute()) restituiscono l’oggetto stesso, consentendo la concatenazione dei metodi.

Le query di inserimento supportano diversi pattern a seconda delle esigenze. In genere, il flusso di lavoro consiste nel definire i campi in cui inserire i dati e specificare i valori che devono essere inseriti. I pattern più utilizzati sono descritti di seguito.

Forma compatta (Compact form)

La forma preferita per la maggior parte delle query è la forma compatta:

<?php
$nid = db_insert('node')
  ->fields(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
  ->execute();
?>

Questa query è equivalente a:

INSERT INTO {node} (title, uid, created) VALUES ('Example', 1, 1221717405);

Il frammento di codice sopra collega le chiavi ai valori da inserire.

<?php
db_insert('node')
?>

Questa riga crea un nuovo oggetto di query per la tabella node.

<?php
  ->fields(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
?>

Il metodo fields() accetta diversi parametri, ma più comunemente un array associativo. Le chiavi dell’array rappresentano le colonne della tabella, mentre i valori rappresentano i dati da inserire. Il risultato è una query di inserimento completa per la tabella specificata.

<?php
  ->execute();
?>

A differenza di altri metodi, execute() non restituisce l’oggetto della query ma il valore del campo auto-increment generato dall’inserimento. Per la tabella node, questo sarà il valore di nid. Se la tabella non contiene un campo auto-increment, il valore restituito sarà indefinito e non dovrebbe essere utilizzato. In generale, questa è la forma di query di inserimento più consigliata.

Forma semplificata (Degenerate form)

<?php
$nid = db_insert('node')
  ->fields(array('title', 'uid', 'created'))
  ->values(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
  ->execute();
?>

Questa query è equivalente alla precedente e produce lo stesso risultato.

<?php
  ->fields(array('title', 'uid', 'created'))
?>

Quando fields() viene chiamato con un array indicizzato anziché associativo, imposta i campi (le colonne del database) che verranno utilizzati nella query, senza specificare i valori. Questo è utile per le query di inserimento multiplo.

<?php
  ->values(array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ))
?>

Il metodo values() definisce un array associativo di coppie campo-valore da inserire. Può anche accettare un array indicizzato: in tal caso, l’ordine dei valori deve corrispondere a quello dei campi definiti in fields(). Con un array associativo, invece, l’ordine non ha importanza, e la leggibilità del codice migliora. Le forme con array indicizzati sono raramente usate, poiché la forma compatta è più comoda. Nella maggior parte dei casi, la separazione tra fields() e values() serve per gestire gli inserimenti multipli.

Inserimento multiplo (Multi-insert form)

L’oggetto di query può accettare più insiemi di valori, chiamando values() più volte. Ogni chiamata aggiunge un nuovo set di dati all’inserimento. Nella maggior parte dei database, le inserzioni multiple vengono eseguite in un’unica transazione per ottimizzare le prestazioni. In MySQL, viene utilizzata una sintassi speciale per gli inserimenti multipli.

<?php
$values = array(
  array(
    'title' => 'Example',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ),
  array(
    'title' => 'Example 2',
    'uid' => 1,
    'created' => REQUEST_TIME,
  ),
  array(
    'title' => 'Example 3',
    'uid' => 2,
    'created' => REQUEST_TIME,
  ),
);
$query = db_insert('node')->fields(array('title', 'uid', 'created'));
foreach ($values as $record) {
  $query->values($record);
}
$query->execute();
?>

Questo codice esegue tre query di inserimento in un unico blocco, sfruttando le ottimizzazioni del driver del database. Nota che abbiamo salvato la query in una variabile per poter ciclare su $values e chiamare values() più volte.

La separazione tra values() e fields(), come nell’esempio, equivale alle seguenti tre query:

INSERT INTO {node} (title, uid, created) VALUES ('Example', 1, 1221717405);
INSERT INTO {node} (title, uid, created) VALUES ('Example2', 1, 1221717405);
INSERT INTO {node} (title, uid, created) VALUES ('Example3', 2, 1221717405);

Nota che nelle query multiple il valore restituito da execute() è indefinito e non deve essere considerato affidabile, poiché varia a seconda del driver del database.

Inserimento basato su una query SELECT (Tabelle derivate)

Se desideri popolare una tabella con i risultati di un’altra query, puoi farlo con un INSERT INTO ... SELECT FROM. In alternativa, puoi elaborare i risultati in PHP e inserirli manualmente.

Supponiamo di voler creare una tabella mytable contenente tutti gli nid e i username delle nodi presenti nel sistema.

Drupal 6

<?php
db_query('INSERT INTO {mytable} (nid, name) SELECT n.nid, u.name FROM {node} n LEFT JOIN {users} u on n.uid = u.uid WHERE n.type = "%s"', array ('page'));
?>

Drupal 7

<?php
// Creiamo la query SELECT.
$query = db_select('node', 'n');
// Join con la tabella users.
$query->join('users', 'u', 'n.uid = u.uid');
// Selezioniamo i campi.
$query->addField('n','nid');
$query->addField('u','name');
// Condizione per ottenere solo nodi di tipo 'page'.
$query->condition('type', 'page');

// Eseguiamo l'inserimento.
db_insert('mytable')
  ->from($query)
  ->execute();
?>

Valori predefiniti (Default values)

Normalmente, se non si specifica un valore per un campo e la tabella ha un valore predefinito per quel campo, il database inserirà automaticamente tale valore. Tuttavia, in alcuni casi può essere necessario forzare esplicitamente l’uso dei valori di default, ad esempio quando si desidera utilizzare solo valori predefiniti per tutti i campi. Questo può essere fatto con il metodo useDefaults():

<?php
$query->useDefaults(array('field1', 'field2'));
?>

Questo codice indica alla query di utilizzare i valori predefiniti per i campi field1 e field2. Nota che definire gli stessi campi sia in useDefaults() che in fields() o values() causerà un errore.

Extra Block Types (EBT) - Nuova esperienza con Layout Builder❗

❗Extra Paragraph Types (EPT) - Nuova esperienza con Paragraphs