Trabajar con una base de datos en Drupal 7 - Lección 3 - Consultas estáticas (SELECT)

La forma más general de consulta en Drupal es la consulta estática. Una consulta estática será enviada a la base de datos literalmente. Solo las consultas de selección (select) pueden ser estáticas.

Las consultas estáticas deben usarse únicamente en consultas muy simples. Debes utilizar consultas dinámicas si necesitas crear una consulta compleja, una consulta generada dinámicamente o modificable tras su ejecución.

Una forma sencilla de ejecutar una consulta estática es a través del método de consulta:

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

Es preferible usar un envoltorio procedimental:

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

Llamar a db_query() como se muestra arriba es equivalente a la siguiente construcción:

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

Veamos por qué es mejor usar db_query que acceder directamente al objeto Database.

db_query() acepta tres argumentos. El primero es la cadena de la consulta, utilizando marcadores de posición (placeholders) donde sea necesario y colocando todos los nombres de tablas entre llaves. El segundo es un array de valores para los marcadores. El tercero, opcional, es un array de configuración sobre cómo ejecutar la consulta.

Prefijos

En las consultas estáticas, todos los nombres de tablas deben ir entre llaves ({}). Esto permite añadir un prefijo a los nombres de las tablas. Los prefijos permiten instalar múltiples sitios en una misma base de datos, usando prefijos distintos como "site1_", "site2_", etc.

Marcadores de posición

Los marcadores indican los lugares donde deben insertarse los valores. Separar los valores del SQL permite a la base de datos distinguir entre la sintaxis SQL y los datos del usuario, ayudando a prevenir inyecciones SQL.

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

El código anterior selecciona todos los nodos creados en la última hora. El marcador :created se reemplaza dinámicamente por el valor de REQUEST_TIME - 3600, donde REQUEST_TIME representa el momento de ejecución. Una consulta puede tener tantos marcadores como se necesiten, pero todos deben tener nombres únicos, incluso si sus valores coinciden.

Según el caso de uso, el array de marcadores puede definirse directamente (como arriba) o antes y pasarse luego. El orden no importa. Los marcadores que comienzan con "db_" están reservados por el sistema y no deben usarse.

Nota: los marcadores deben ir entre comillas o no dependiendo de su tipo. Por ejemplo, las cadenas deben ir entre comillas, los números no.

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

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

Los marcadores no deben usarse para nombres de tablas o columnas. Solo sirven para sustituir cadenas o valores numéricos.

Arrays de marcadores

La capa de base de datos de Drupal incluye una característica especial para marcadores. Si se pasa un array como valor de marcador, Drupal lo convierte automáticamente en una lista separada por comas. Así los desarrolladores no necesitan preocuparse por contar marcadores manualmente. Veamos un ejemplo:

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

// Usando múltiples marcadores:
db_query("SELECT * FROM {node} WHERE nid IN (:nids_1, :nids_2, :nids_3)", array(
  ':nids_1' => 13,
  ':nids_2' => 42,
  ':nids_3' => 144,
));
// Equivale a:
db_query("SELECT * FROM {node} WHERE nid IN (13, 42, 144)");
?>

Parámetros de consulta

El tercer parámetro de db_query() son los parámetros de consulta: un array que define cómo debe manejarse la consulta. Generalmente se usan dos parámetros con más frecuencia. Los demás son para uso interno.
La clave "target" define el propósito de la consulta. Si no se especifica, se usa "default". Actualmente, "slave" indica que la consulta debe ejecutarse en un servidor esclavo si está disponible. La clave "fetch" determina cómo se devolverán los resultados desde la base de datos. Los valores posibles incluyen: PDO::FETCH_OBJ, PDO::FETCH_ASSOC, PDO::FETCH_NUM, PDO::FETCH_BOTH o el nombre de una clase. Si se define una cadena, cada registro se devolverá como un objeto de esa clase.
El comportamiento de cada valor está definido por PDO y permite obtener resultados como un objeto stdClass, un array asociativo, un array numérico o ambos a la vez.

1. PDO::FETCH_OBJ - objeto.
2. PDO::FETCH_ASSOC - array asociativo.
3. PDO::FETCH_NUM - array numérico.
4. PDO::FETCH_BOTH - array con claves numéricas y asociativas.

Consulta http://php.net/manual/en/pdostatement.fetch.php. Por defecto se usa PDO::FETCH_OBJ, y puede seguir usándose si no tienes preferencias específicas.

En este ejemplo, la consulta se ejecutará en un servidor esclavo si está disponible y los resultados se devolverán como array asociativo:

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