Pagina principal ADODB en español

Libreria de ADOdb para el Diccionario de Datos en PHP

V4.29 29 Ago 2006 (c) 2000-2006 John Lim (jlim#natsoft.com.my).
AXMLS (c) 2004 ars Cognita, Inc

Este programa tiene licencia dual BSD-Style y LGPL. Esto significa que lo puedes usar tanto en productos comerciales como en propietarios.

Ligas utiles de ADOdb: Descarga   Otros manuales

Este documento describe una libreria de clases en PHP para automatizar la creacion de tablas, indices y llaves foraneas con portabilidad para multiples bases de datos. Richard Tango-Lowy y Dan Cech han sido muy amables contribuyendo con AXMLS, un sistema de esquemas en XML para definir bases de datos.

Actualmente las siguientes bases de datos estan soportadas:

Bien probadas: PostgreSQL, MySQL, Oracle, MSSQL.
Calidad Beta: DB2, Informix, Sybase, Interbase, Firebird.
Calidad Alfa: MS Access (no maneja valores por omision, DEFAULT ) y ODBC generico.

Ejemplo de Uso

  include_once('adodb/adodb.inc.php');
  # Primero de crea una conexion normal
  $db->NewADOConnection('mysql');
  $db->Connect(...);

  # Creeamos un objeto de diccionario de datos, usando esta conexion
  $dict = NewDataDictionary($db);

  # Tenemos una declaracion nativa de diccionario de datos en ADOdb, similar al SQL.
  # Los tipos de campos usan codigos de un caracter, y los campos son separados por ','.
  # El siguiente ejemplo crea 3 campos: "col1", "col2" and "col3":
  $flds = " 
   col1 C(32) NOTNULL DEFAULT 'abc',
   col2 I  DEFAULT 0,
   col3 N(12.2)
  ";

  # Demostracion de la creacion de tablas e indices
  $sqlarray = $dict->CreateTableSQL($tabname, $flds, $taboptarray);
  $dict->ExecuteSQLArray($sqlarray);
$idxflds = 'co11, col2'; $sqlarray = $dict->CreateIndexSQL($idxname, $tabname, $idxflds); $dict->ExecuteSQLArray($sqlarray);

Constructor de la clase

NewDataDictionary($connection, $drivername=false)

Crea un nuevo objeto de diccionario de datos. Puedes dar como argumento un objecto de conexion a la base de datos en $connection. Esta $connection puede no estar todavia conectada a la base de datos. Algunos objetos de conexion a bases de datos son genericos (es decir odbtp y odbc). Desde la version 4.53, le puedes decir a ADOdb el nombre real de la base de datos con el parametro $drivername. Ejemplo:

$db =& NewADOConnection('odbtp');
$datadict = NewDataDictionary($db, 'mssql'); # force mssql

Funciones de la Clase

funcion CreateDatabase($dbname, $optionsarray=false)

Crea la base de datos con el nombre $dbname;

funcion CreateTableSQL($tabname, $fldarray, $taboptarray=false)

  REGRESA:      un arreglo de cadenas de caracteres, el sql a ejecutar, o falso
  $tabname:     nombre de la tabla
  $fldarray:    cadena (o arreglo) conteniendo informacion del campo
  $taboptarray: arreglo conteniendo opciones de la tabla

El nuevo formato de $fldarray emplea un formato de texto libre, donde cada campo esta delimitado por ",". El primer elemento de cada campo es el nombre del campo seguido por el tipo y opcionalmente el tamaņo del campo. Los parametros opcionales van en $otheroptions:

  "$fieldname $type $colsize $otheroptions"

El viejo formato (y todavia soportado) de $fldarray es un arreglo bi-dimensional, donde cada renglon en la primera dimension represente un campo, Cada renglon tiene el siguiente formato:

  array($fieldname, $type, [,$colsize] [,$otheroptions]*)

Los primeros dos campos deben ser el nombre del campo y el tipo del campo. El tipo de campo puede ser el codigo de tipo portable o el tipo de campo para la base de datos.

Los codigos de tipo portables validos son::

  C:  varchar
  X:  campos varchar muy largos (TEXT)
  XL: Para Oracle, toma CLOB, para las demas igual que 'X' 

  C2: Multibyte varchar
  X2: Multibyte varchar (largest size)

  B:  BLOB (binary large object) (BYTE)

  D:  Fecha (algunas bases de datos no lo manejan y se toman del tipo datetime)
  T:  Datetime o Timestamp
  L:  Entero field suitable for storing booleans (0 or 1)
  I:  Entero (mapeado a I4)
  I1: 1-byte Entero
  I2: 2-byte Entero
  I4: 4-byte Entero
  I8: 8-byte Entero
  F:  Numero de punto flotante
  N:  Numero decimal

El campo $colsize representa el tamaņo del campo. Si es un numero decimal entonces se asume el que numero siguiendo el punto es la precision, entonces 6.2 significa un numero decimal de 6 digitos con 2 decimales. Se recomienda que el valor por omision para tipos numericos sea representado como cadena de caracteres para evitar algun error de redondeo.

El campo $otheroptions puede incluir los siguientes terminos (sin importar mayusculas o minusculas):

  AUTO            Para numeros de auto-incremento. Emulado con triggers si no esta disponible.
                  Activa tanbien NOTNULL.
  AUTOINCREMENT   Igual que AUTO.
  KEY             Campo de llave primario. Activa tambien NOTNULL. Acepta llaves compuestas.
  PRIMARY         Igual que KEY.
  DEF             Sinonimo de DEFAULT para mecanografos flojos.
  DEFAULT         El valor por omision. Las cadenas de caracteres se auto encomillan a menis
                  que la cadena empieze y termine con espacios, ej ' SYSDATE '.
  NOTNULL         El campo no acepta nulos.
  DEFDATE         Asigna valor por omision para llamar a la funcion que obtiene la fecha de hoy.
  DEFTIMESTAMP    Asigna el valor por omision para llamar a la funcion que obtiene el timestamp actual.
  NOQUOTE         Previene que se haga un auto encomillado de los valores por omision.
  CONSTRAINTS     Restricciones adicionales definidas al final de la definicion del campo.

El Diccionario de Datos acepta dos formatos, la antigua especificacion de arreglospecification:

  $flds = array(
    array('COLNAME',   'DECIMAL', '8.4', 'DEFAULT' => 0, 'NOTNULL'),
    array('id',        'I'      , 'AUTO'),
    array('`MY DATE`', 'D'      , 'DEFDATE'),
    array('NAME',      'C'      , '32', 'CONSTRAINTS' => 'FOREIGN KEY REFERENCES reftable')
  );

O el formato declarativo mas simple:

  $flds = "
    COLNAME DECIMAL(8.4) DEFAULT 0 NOTNULL,
    id I AUTO,
    `MY DATE` D DEFDATE,
    NAME C(32) CONSTRAINTS 'FOREIGN KEY REFERENCES reftable'
  ";

Observa que si tenemos caracteres especiales en el nombre del campo (e.j. My Date), hay que encerrarlo entre comillas invertidas (`). Normalmente los nombres de los campos no diferencian entre amyusculas y minusculas, pero si se encierran entre comillas invertidas, algunas bases de datos si hacen la diferenciacion y otras no. Se cuidadoso.

El tercer parametro de la funcion CreateTableSQL es $taboptarray. Este contiene valores especificos para la tabla. Los parametros posibles incluyen:

Opciones especificas de la tabla tambien pueden ser definidas usando el nombre del tipo de la base de datos como llave del arreglo. En el siguiente ejemplo, para MySQL crear la tabla de tipo ISAM, si se usa Oracle almacenar la tabla en tablespace "users". Y como se especifica REPLACE, borrarla tabla primero.

  $taboptarray = array('mysql' => 'TYPE=ISAM', 'oci8' => 'tablespace users', 'REPLACE');

Tambien se pueden definir restricciones de llaves foraneas (foreignkey constraints). A continuacion la sintaxis para postgresql:

  $taboptarray = array('constraints' => ', FOREIGN KEY (col1) REFERENCES reftable (refcol)');

funcion DropTableSQL($tabname)

Regresa el enunciado SQL para borrar la tabla especificada.

funcion ChangeTableSQL($tabname, $flds)

Verifica que la tabla exista, si la tabla no existe se comporta como CreateTableSQL. Si la tabla si existem genera el enunciado ALTER TABLE MODIFY COLUMN apropiado si el campo ya existe o ALTER TABLE ADD $column si el campo no existe.

La clase debe de estar conectada a la base de datos para que ChangeTableSQL detecte la existencia de la tabla. Idea y codigo contribuido por Florian Buzin.

funcion RenameTableSQL($tabname,$newname)

Renombra una tabla. Regresa un arreglo de cadenas de texto, el cual es el enunciado SQL requerido para renombrar la tabla. Desde la version 4.53 de ADOdb. Proporcionado por Ralf Becker.

funcion RenameColumnSQL($tabname,$oldcolumn,$newcolumn,$flds='')

Renombre un campo de la tabla. Regresa un arreglo de caracteres, conteniendo el enunciado SQL requerido para cambiarle el nombre a la columna. El parametro opcional $flds is un texto que define una columna como para AddColumnSQL, por el momento solo se usa para mysql. Dispponible desde la version ADOdb 4.53. Contribuido por Ralf Becker.

funcion CreateIndexSQL($idxname, $tabname, $flds, $idxoptarray=false)

  REGRESA:      un arreglo de cadenas de caracteres, los enunciados SQL a ejecutar o falso
  $idxname:     nombre del indice
  $tabname:     nombre de la tabla
  $flds:        lista de campos como una cadena separada por comas o arreglo de cadenas
  $idxoptarray: arreglo de opciones de creacion de indices

$idxoptarray es similar a $taboptarray ya que tambien acepta informacion especifica del indice. Otras opciones incluye:

  CLUSTERED     Crea el indice agrupado (solo mssql)
  BITMAP        Crea el indice de mapa de bits (solo oci8)
  UNIQUE        Hace el indice unico
  FULLTEXT      Hace el indice fulltext (solo mysql)
  HASH          Hace el indice hash (solo postgres)
  DROP          Borra un indice anterior 

funcion DropIndexSQL ($idxname, $tabname = NULL)

Regresa el enunciado SQL para borrar el indice especificado.

funcion AddColumnSQL($tabname, $flds)

Agrega una o mas columnas. NO hay garantia de que funcione en todos los casos.

funcion AlterColumnSQL($tabname, $flds)

Advertencia, no todas las bases de datos manejan esta funcionalidad.

funcion DropColumnSQL($tabname, $flds)

Borra una o mas columnas.

funcion SetSchema($schema)

Asigna el esquema.

funcion &MetaTables()

funcion &MetaColumns($tab, $upper=true, $schema=false)

funcion &MetaPrimaryKeys($tab,$owner=false,$intkey=false)

funcion &MetaIndexes($table, $primary = false, $owner = false)

Estas funciones son envoltorios para las funciones correspondientes en el objeto conexion. Sin embargo el nombre de las tablas se encomillara automaticamente por la funcion TableName (ver abajo) antes de ser mandado al objeto conexion.

funcion NameQuote($name = NULL)

Si la nombre proporcionado esta con comillas invertidas (`) o contiene caracteres especiales, regresa el nombre encerrado entre las comillas adecuadas, en caso contrario el nombre se regresa sin cambios.

function TableName($name)

Lo mismo que NameQuote, por le agregara al principio el esquema actual.

function MetaType($t,$len=-1,$fieldobj=false)

function ActualType($meta)

Convierte entre los codigos de tipo independientes de la base de datos ('Meta') y los tipos especificos de la base de datos ('Actual').

function ExecuteSQLArray($sqlarray, $contOnError = true)

  REGRESA:      0 isi falla, 1 si ejectuta todo pero con errores, 2 si se ejecuto satisfactoriamente
  $sqlarray:    un arreglo de cadenas de caracteres con el codigo SQL (sin punto y coma al
                final de la cadena)
  $contOnError: Si verdadero, la ejecucion continua aun si hay errores

Ejecuta un arreglo del comandos SQL regresado por CreateTableSQL o CreateIndexSQL.


ADOdb XML Schema (AXMLS)

Esta es una clase contribuida por Richard Tango-Lowy y Dan Cech que permite que el usaurio rapida y facilmente construya una base de datos usando la excelente libreria de bases de datos ADOdb y un archivo sencillo con formato XML. Se puede descargar la ultima version de AXMLS aqui.

Inicio Rapido

Adodb-xmlschema, o AXMLS, es un conjunto de clases que permite al usuario crear o actualizar una base de datos rapida y facilmente en casi cualquier motor de base de datos usando la excelente libreria de base de datos ADOdb y un secillo archivo de esquema en formato XML. Nuestro bjectivo es proporcionar a los desarrolladores una herramienta que sea simple de usar pero que les permita crear un archivo simple que pueda crear, actualizar, y manipular bases de datos en la mayoria de los motores de base de datos.

Instalando axmls

La manera mas sencilla de instalar AXMLS es descargar e instalar cualquier version reciente de la libreria de abstraccion de base de datos ADOdb. Para instalar AXMLS manualmente, simplemente copia el archivo adodb-xmlschema.inc.php y el directorio xsl a tu directorio de adodb.

Usando AXMLS en tu Aplicacion

Hay dos pasos involucrados para usar AXMLS en tu aplicacion: primero debess crear un esquema, o representacion XML de tu base de datos, y segundo, debes de crear el codigo PHP que analizara y ejecutara el esquema.

Empezemos con un esquema que describa una tipica aunque simplista tabla para la adminstracion de usuarios para una aplicacion.

<?xml version="1.0"?>
<schema version="0.2">

  <table name="users">
    <desc>Tipica tabla de usuarios para una aplpicacion.</desc>
    <field name="userId" type="I">
      <descr>Identificador Unico asignado a cada usuario.</descr>
      <KEY/>
      <AUTOINCREMENT/>
    </field>
    
    <field name="userName" type="C" size="16"><NOTNULL/></field>
    
    <index name="userName">
      <descr>Crear un indice unico en el nombre del usuario</descr>
      <col>userName</col>
      <UNIQUE/>
    </index>
  </table>
  
  <sql>
    <descr>Insertar algunos valores en la tabla de usuarios.</descr>
    <query>insert into users (userName) values ( 'admin' )</query>
    <query>insert into users (userName) values ( 'Joe' )</query>
  </sql>
</schema>			

Veamos a detalle este esquema.

La etiqueta de apertura <?xml version="1.0"?> es requerida por XML. La etiqueta <schema> le dice al analizador que las marcas adjuntas definen un esquema XML. El atributo version="0.2" define la version de la hoja DTD de AXMLS usada por el esquema XML.

Todas las versiones de AXMLS anteriores a la version 1.0 tienen una version de esquema de "0.1". La version actual de esquema es "0.2".

<?xml version="1.0"?>
<schema version="0.2">
  ...
</schema>

Despues definimos una o mas tablas. Una tabla consiste de campos (y otros objetos) encerrados en etiquetas <table>. El atributo name="" especifica el nombre de la tabla que sera creada en la base de datos.

<table name="users">

    <desc>A typical users table for our application.</desc>
    <field name="userId" type="I">
      <descr>A unique ID assigned to each user.</descr>
      <KEY/>
      <AUTOINCREMENT/>
    </field>
    
    <field name="userName" type="C" size="16"><NOTNULL/></field>
    
</table>

Esta tabla se llama "users" y tiena una descripcion y dos campos. La descripcion es opcional, y actualmente es solo para tu propia informacion, no se aplica a la base de datos.

La primera etiqueta <field> creara un campo llamado "userId" del tipo "I", o integer. (Ve la documentacion del Diccionario de Datos de ADOdb para una lista de tipos validos) Esta etiqueta <field> encierra dos opciones de campo especiales: <KEY/>, que especifica el campo como una llave primaria y <AUTOINCREMENT/>, que especifica que el motor de la base de datos debe de llenar este campo con el siguiente valor cuando se inserte un registro.

La segunda etiqueta <field> creara un campo llamado "userName" de tipo "C", o character, y de longitud de 16 caracteres. La opcion <NOTNULL/> especifica que este campo no permite nulos (NULL).

hay dos maneras de agregar indices a la tabla. La manera mas sencilla es marcar un campo con la opcion <KEY/> coo se describio arriba; una llave primare es un indice unico. El segundo y mas poderoso metodo usa la etiqueta <index>.

<table name="users">
  ...
    
  <index name="userName">
    <descr>Crea un indice unico en el nombre del usuario</descr>
    <col>userName</col>
    <UNIQUE/>
  </index>
    
</table>

La etiqueta <index> especifica que un indice se creara en la tabla que la encierra. El atributo name="" proporciona el nombre del indice que sera creado en la base de datos. La descripcion, como se dijo anteriormente, es unicamente para tu informacion. La etiqueta <col> lista cada columna que sera incluida en el indice. Finalmente la etiqueta <UNIQUE/> especifica que este sera un indice unico.

Finalmente, AXMLS te permite incluir codigo SQL arbitrario que sera aplicado a la base de datos cuando el es esquema se ejecute.

<sql>
  <descr>Inserta algunos valores en la tabla de usuarios.</descr>
  <query>insert into users (userName) values ( 'admin' )</query>
  <query>insert into users (userName) values ( 'Joe' )</query>
</sql>

La etiqueta <sql> encierra cualquier numero de querys SQL que tu definas para tu uso propio.

Ahora que ya deinimos el esquema XML, necesitas saber como aplicarlo en tu base de datos. Aqui esta un codigo PHP muy simple que muestra como cargar el esquema.

<?PHP
/* Hay que decirle al programa donde encontrar las librerias ADOdb y AXMLS.
 */
require( "adodb/adodb.inc.php");
require( "adodb/adodb-xmlschema.inc.php" );

/* Informacion de configuracion. Define el nombre del archivo del esquema,
 * plataforma de base de datos (lea la documentacion de ADOdb para los
 * nombres validos de plataformas), y la informacion para la conexion.
 */
$schemaFile = 'example.xml';
$platform = 'mysql';
$dbHost = 'localhost';
$dbName = 'database';
$dbUser = 'username';
$dbPassword = 'password';

/* Iniciamos creando una conexion normal de ADODB.
 */
$db = ADONewConnection( $platform );
$db->Connect( $dbHost, $dbUser, $dbPassword, $dbName );

/* Usamos la conexion a la base de datos para crear un nuevo objeto adoSchema.
 */
$schema = new adoSchema( $db );

/* Llamamos a ParseSchema() para construir el SQL en base al archivo de esquema XML.
 * Entonce llamamos a  ExecuteSchema() para aplicar el SQL obtenido a la base de
 * datos.
 */
$sql = $schema->ParseSchema( $schemaFile );
$result = $schema->ExecuteSchema();
?>

Veamos a cada parte de este ejemplo por partes. Despues de que creas manualmente la base de datos, se requieren tres pasos para cargar (o actualizar) tu esquema.

Primero, crear una conexion a ADOdb normal. Las variables y los valores aqui deben ser squellos requeridos para canectarse a tu base de datos.

$db = ADONewConnection( 'mysql' );
$db->Connect( 'host', 'user', 'password', 'database' );

Segundo, crear el objeto que carga y manula tu esquema. Se pasa como parametro el objeto ADodb de conexion a la base de datos para crear el objeto adoSchema .

$schema = new adoSchema( $db );

Tercero, se llama a ParseSchema() para analizar el esquema y despues a ExecuteSchema() para aplicarlo a la base de adtos. Debes de pasar a ParseSchema() la ruta y el nomnre del archivo de tu esquema.

$schema->ParseSchema( $schemaFile ); 
$schema->ExecuteSchema(); 

Ejecuta el codigo anterior y despues conectate a tu base de datos. Si hiciste todo bien, deberas ver tus tablas, indices y sql.

Puedes encontrar los archivos fuentes de este tutorial en el directorio 'examples' como tutorial_shema.xml y tutorial.php. Ve la documentacion de la clase para una descripcion mas detallada de los metodos de adoSchema, incluyendo metodos y elemntos del esquema que no estan descritos en este tutorial.

XML Schema Version 3

En Marzo del 2006, liberamos adodb-xmlschema03.inc.php, el cual soporta la version 3 del schema XML. El archivo adodb-xmlschema.inc.php sigue igual que en versiones anteriores, y soporta la version 2 del esquema XML. La Version 3 proporciona algunas mejoras:

Ejemplo de uso:

<?xml version="1.0"?>
<schema version="0.3">
 <table name="ats_kb">
  <descr>ATS KnowledgeBase</descr>
  <opt platform="mysql">TYPE=INNODB</opt>
  <field name="recid" type="I"/>
  <field name="organization_code" type="I4"/>
  <field name="sub_code" type="C" size="20"/>
  etc...

Para usarlo, cambia tu codigo para incluir adodb-xmlschema03.inc.php.

Actualizandose

Si tu version de esquema es antigua, entonces se usa XSLT para transformar el esquema a la version mas nueva. Esto significa que si estas usando un formato de esquema XML antigua, debes de tener la extension XSLT instalada. Si no quieres obligar a tus usuarios a tener la extension XSLT instalada, asegurate de modifcar tu esquema XML para que coincida con la ultima version.
Si tienes alguna pregunta o comentario, por favor manda un correo a Richard en la direccion richtl#arscognita.com.