¿Qué es ADOdb?

ADOdb, también conocido como Active Data Objects DataBase, es una capa de abstracción para acceso a datos que puede utilizarse con versiones 4.0.4 o superiores de PHP. También existen versiones para Python.
Se trata de un conjunto de clases y funciones que facilitan el trabajo con bases de datos.

Portabilidad

Estas clases y funciones de ADOdb nos aportan portabilidad, al permitirnos simplificar al máximo el proceso de migración de un motor de bases de datos a otro agregando una capa intermedia de acceso a estos motores.
Si bien la ventaja de la portabilidad se ve oscurecida por el agregado de una capa extra, sigue siendo una buena idea ya que estandarizaremos el código y mejoraremos su legibilidad, obviando las particularidades del lenguaje SQL que cada motor implementa.
ADOdb soporta los siguientes motores de bases de datos: MySQL, PostgreSQL, Oracle, Interbase, Firebird, DB2, Microsoft SQL Server, Microsoft Access, Microsoft Visual FoxPro, SQLite (solo con PHP5), Sybase4, Informix y otras mediante ODBC.
La instalación es muy simple, solo hay que descomprimir el paquete descargado en un directorio accesible por PHP y agregar:

include('adodb/adodb.inc.php');

Este archivo contiene el punto de partida para comenzar a utilizar ADOdb. En él se definen clases, variables globales y constantes que son vitales para el funcionamiento correcto de la librería.

Diferentes clases y objetos que componen ADOdb

Considerar comentar y explicar detalladamente cada entidad de esta librería culminaría con la realización de un artículo en demasía largo. Es preferible para un rápido acercamiento a la misma explicar las funciones, clases y constantes de uso común, dejando al lector especializarle luego en los temas que requiera.

Comenzaré por comentar 3 clases importantes, algunas de ellas las usaremos directamente, otras serán respuesta de llamados a funciones y métodos de objetos.

ADOConnection

Esta es una clase abstracta, es la base para crear clases concretas de drivers para las diferentes bases de datos que soporta ADOdb.
Un driver en ADOdb no es más que una implementación de esta clase que completa con métodos y propiedades específicos del motor que modelará.
Dichos drivers deben escribirse en archivos con extensión *.inc.php a colocarse en el directorio ADO_HOME/drivers.
Algunos ejemplos que podrían mencionarse son: adodb-mysql.inc.php y adodb-firebird.inc.php. Existen drivers de todo tipo y color, es cuestión de saber seleccionar el correcto, el cual depende del motor que estemos utilizando y a veces, del sistema operativo donde corre. Es importante destacar que cualquiera puede escribir sus propios drivers para motores nuevos, aunque es recomendable utilizar los ya muy probados drivers que proporciona ADOdb.

ADONewConnection($driver|$dsn);

ADONewConnection es una función frabricante de objetos. Dependiendo del parámetro provisto se comporta de manera diferente, pero siempre retornando un objeto descendente de ADOConnection, es decir una implementación específica de una conexión a una base de datos. Básicamente esta función crea un objeto asociado a un tipo de motor de bases de datos.

Los parámetros aceptados son de tipo string. Si proporcionamos el nombre del driver en $driver (por ejemplo 'mysql') entonces esta función creará un objeto de conexión apropiado para este tipo de motor, pero no realizará ningún tipo de conexión a la base de datos. Para ello deberemos utilizar posteriormente un método del objeto retornado del cual hablaremos muy pronto.
Son muchos los motores que soporta, entre ellos podemos mencionar algunos valores para el argumento $driver: 'db2', 'ibase', 'firebird', 'informix', 'mssql', 'mysql', 'mysqli', 'oci', 'odbc', 'postgres7', y un largo etc.

Al crear un objeto de este tipo se crea una conexión, si se proporciona un $dsn conteniendo una cadena DSN de conexión, que no está activa hasta decidir el tipo de conexión, la cual puede ser persistente o no.
Las ventajas de las conexiones persistentes radica en su rapidez dado que la conexión a la base de datos nunca se cierra (incluso al invocar Close()). Las conexiones no persistentes requieren muchos menos recursos del sistema, evitando el riesgo de sobrecarga del mismo.

El formato dsn (data source name) es el siguiente:

$driver://$username:$password@hostname/$database?options[=value]

ADONewConnection invoca internamente Connect() o PConnect(), solo si pasamos un dsn váido. Si la conexión falla, regresa false.

Los metodos Connect y PConnect son muy similares, al menos en cuanto a sus parámetros, en los cuales básicamente deberemos proporcionar:

Connect($argHostname = "", $argUsername = "", $argPassword = "", $argDatabaseName = "") 

Si estos parametros no son proporcionados, o son cadenas vacías, se utilizarán los valores almacenados en las variables de configuración.

Una vez realizada una conexión podremos comenzar a consultar la base de datos, realizando selecciones, inserciones, actualizaciones, etc.

ADORecordSet

Descendiente de IteratorAggregate, se trata de un iterador que simplifica la manipulación de resultados de consultas a la base de datos. Este tipo de objeto es retornado por métodos una clase ADOConnection, métodos tales como Execute y SelectLimit por nombrar algunos.
Los métodos y propiedades de ADORecordSet nos permiten entro otras cosas conocer la cantidad de registros retornados por la consulta SQL, moverse en diferentes direcciones en la colección de registros, recuperar una fila completa, etc.

Veamos ahora como funcionan estos objetos en un ejemplo para comprender mejor su funcionamiento general.

try

{

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

}

catch (exception $e)

{

	die($e->getMessage());

}

En el código vemos que creamos un objeto de conexión del tipo 'mysql', y luego intentamos conectarnos proporcionando los parametros almacenados en las constantes _db_*.
Si $connected contiene algo distinto a 0 o false, entonces lanzamos una excepción capturada luego en el bloque catch.
En el caso de estar conectados, ya podemos enviar consultas a la base de datos. En este caso especificamos al motor de mysql que utilizaremos la codificación UTF8 en las consultas SQL que posteriormente utilizaremos.

Listado de propiedades y métodos

Las propiedades y métodos más usuales y que seguramente utilicemos en nuestros desarrollos pueden enumerarse en la siguiente lista. Proporcionaré una breve descripción de cada uno de ellos.

connect($host, $user, $pass, $database);

Como ya vimos, Connect realiza la conexión específica a una base de datos. Necesita conocer el host que contiene el servidor funcionando de la base de datos, el usuario y su contraseña, y por ultimo el nombre de la base de datos a la que queremos conectarnos.
Si falla la conexión regresa false, en caso contrario retorna un valor verdadero. Se puede utilizar PConnect para realizar conexiones persistentes.

isConnected()

Si Connect es exitosa, entonces isConnected retorna un valor verdadero. En el caso que cualquier error no haya permitido realizar al conexión, se retornará falso.

Execute($sql);

Proporcionando una sentencia en lenguaje SQL, Execute retornará un objeto del tipo ADORecordSet conteniendo mucha información sobre la conexión, la consulta y, naturalmente, sobre el resultado de dicha consulta.
Cabe destacar que Execute puede ejecutar consultas que retornen cursores y que no retornen cursores, o lo que es lo mismo: Execute puede ejecutar consultas DDL y DML.

select_limit($sql, $count, $from);

Método que abstrae las diferentes implementaciones de limitación de registros retornados.
Cada motor lo suele implementar de una manera diferente. Select_Limit nos abstrae de estas diferentes implementaciones proporcionandonos un punto común para realizar consultas restringidas o limitadas en resultados.
$sql es una consulta SELECT normal (sin restricciones), $count es la cantidad de registros máximos que queremos recibir y $from el número de registro desde el cual comenzar el conteo hasta $count.
Un método muy util para realizar reportes o paginaciones en nuestros sistemas.

getOne($sql);

Supongamos que queremos obtener un solo valor de una consulta, por ejemplo si $sql contuviera:

SELECT MAX(puntos) FROM equipos WHERE zona = 1

Y quisieramos que ese valor se guarde automáticamente en una variable de tipo entero o flotante, deberiamos escribir el siguiente código utilizando el método getOne:

$maximo_puntos_zona1 = $db->getOne($sql);

Y $maximo_puntos_zona1 ya tendría un valor numérico para trabajarlo como necesitemos.

Prepare

A este método, y sus asociados, los veremos en detalle en la sección de optimizaciones. Básicamente una consulta preparada, si el motor al que estamos conectados soporta consultas preparadas, prepara a la base de datos para recibir colecciones de valores aplicables a una consulta SQL patrón o modelo. Esto agiliza de gran manera la performance del sistema.

Todos los metodos anteriormente descriptos pertenecen a un objeto del tipo ADOConnection. Algunos de ellos retornan objetos del tipo ADORecordSet, como es el caso de Execute. A continuación veremos los métodos que tenemos para trabajar con estos conjuntos de datos retornados, modelados por objetos ADORecordSet.

Affected_Rows

Si ejecutamos una consulta de Inserción, Actualización o Eliminación de registros, Affected_Rows nos devolvera la cantidad de registros que han sido afectados por la última consulta ejecutada.

RecordCount

Similar al anterior pero aplicable solo a consultas de selección.

FetchRow
FetchNextObject
FetchNextObj
GetRowAssoc

Estos métodos retornan una fila, la siguiente fila del cursor de resultados, en diferentes formatos. Como objeto, como array numérico, como array asociativo.
Usualmente son utilizados en ciclos iterativos.

Fields[$col]

Se trata de una propiedad, un array asociativo que nos dá acceso a partir del indice $col, que debe contener el identificador de columna que queremos accesar de la fila activa.

MoveNext
MoveFirst
MoveLast
Move($n)

Metodos relacionados con la posición del cursor. Permiten movernos al principio, al final, a la siguiente fila o directamente a una posición absoluta dentro de la colección.

Además de estos métodos, ADOdb pone a disposición una gran cantidad de funciones para manejo de errores, manejo de cadenas de caracteres, de campos BLOBs, fechas, y más.

Antes de continuar es muy útil mencionar la existencia de una propiedad denominada debug del objeto de conexión el cual se encarga de volcar por la salida standart una serie de logs provenientes de la ejecución, correcta o incorrecta de sentencias SQL que vayamos ejecutando. Para ello debemos asignarle un valor distinto verdadero, como por ejemplo true.

Ejemplos completos

Comencemos a utilizar ADOdb con algunos ejemplos sencillos. Intentaré dar ejemplos del estilo copiar y pegar para que puedan utilizarlos directamente, o casi, a medida que van siguiendo el artículo.
Comenzaremos por las selecciones, de las que hay varias formas de conseguir resultados, para después comenzar a modificar datos haciendo inserciones, actualizaciones y eliminaciones.

SELECT

Haremos uso de los métodos más comunes, tratando de dar consejos de su uso más adecuado.
Aclaro que existe el método Query pero este existe solo por compatibilidad con PEAR DB Compat.
Ahora, si bien es posible utilizar Execute para obtener un objeto RecordSet para asi obtener los resultados, trataremos de usar métodos un poco más especializados dependiendo el objetivo que estemos buscando.

Si lo que estamos necesitando es solo un valor, por ejemplo cuando queremos una cantidad de registros de una tabla usaremos lo siguiente:

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "SELECT COUNT(*) AS c FROM dioses";

	$dioses_count = $db->GetOne($query);

?>

Luego $dioses_count contendrá el único valor resultado de la consulta.

Si lo que buscamos es solo una fila, usaremos lo siguiente:

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "SELECT * FROM dioses WHERE pais = 'AR'";

	$first_god_of_argentina = $db->GetRow($query);

	echo $first_god_of_argentina['nombre'];

?>

$first_god_of_argentina es un array que contiene claves para acceder cada una de las columnas resultado.

Dado que utilizaremos ADOdb mayormente para desarrollo web, es una buena costumbre limitar los resultados de la consulta, ya sea paginando o como se les ocurra.
Para ello y para cuidar un poco el servidor, los motores disponen de palabras clave para precisamente limitar el número de resultados a retornar. Es por ello que me centraré en los métodos "Limit".
Si queremos recuperar todas las filas de la consulta limitadas por una cantidad hacemos:

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "SELECT * FROM dioses";

	$gods_rs = $db->SelectLimit($query, 100, 200);

	print_r($gods_rs->GetArray());

?>

Aqui lo que hacemos es realizar la consulta limitandola a 100 resultados comenzando por fila 200 (sería la tercer página de nuestro paginado). El resultado es un RecordSet, del cual utilizaremos el método GetArray para que nos retorne el array que imprimiremos en pantalla.

Existe otro caso común es recuperar un array asociativo con clave igual al id y valor igual a un titulo, un nombre, o algo similar... si estoy hablando del caso típico de completar un html select.
Supongamos que tenemos una tabla paises con columnas como iso3 y nombre, lo que queremos es retornar un array como este:

<?php

array(

	'ARG' => 'Argentina',

	'ESP' => 'España',

	'MEX' => 'Mexico', ...

)

?>

Para esto ADOdb proporciona el método GetAssoc.

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "SELECT iso3, nombre FROM paises";

	$paises = $db->GetAssoc($query);

?>

Luego $paises es un array como el descripto.

INSERT

Para insertar una nueva fila en una tabla crearemos la consulta como string y la ejecutaremos.
Para ello, utilizaremos el método Execute del objeto de conexión.

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "INSERT INTO dioses (nombre, apellidos) ";

	$query .= "VALUES ('Diego', 'Maradona')";

	$db->execute($query);

	$last_inserted_id = $db->Insert_ID();

?>

Luego en $last_inserted_id tendremos el id de la fila recien insertada (en el caso de MySQL se aplica a tablas con primary keys enteras auto incrementales).

UPDATE

Las actualizaciones son muy parecidas a las inserciones. Se utiliza el método Execute.

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "UPDATE dioses SET nombre = 'Diego Armando' ";

	$query .= "WHERE nombre = 'Diego' AND apellidos = 'Maradona'";

	$db->execute($query);

	$affected_rows = $db->Affected_Rows();

?>

Aqui Affected_Rows retornará las filas que han sufrido cambios.

DELETE

Usando el método Execute realizaremos eliminaciones.

<?php

	$db = ADONewConnection('mysql');

	$connected = @$db->Connect(_db_host, _db_user, _db_pass, _db_name);

	if(!$connected)

		throw new Exception('No pudimos conectarnos a la BD...');

	$db->Execute("SET NAMES 'utf8'");

	$query = "DELETE FROM dioses WHERE nombre = 'Diego Armando'";

	$db->execute($query);

	$affected_rows = $db->Affected_Rows();

?>

Aqui Affected_Rows retornará las filas que han sido eliminadas.