Edición de «MODELOS»

= Introducción =
Kumbia posee una doble capa de abstracción de base de datos. La primera mantiene un acceso uniforme que evita reescribir código en caso de cambiar el motor de almacenamiento y la segunda llamada ActiveRecord que está basada en su análogo de Rails; permite mapear las relaciones de la base de datos a objetos. Este mapeo permite el fácil acceso y modificación de las relaciones de la base de datos. Este capítulo explica la creación de estos objetos, la forma en que trabajan y cómo integrarlos con las demás partes de la arquitectura. 

= ¿Por qué usar una capa de Abstracción?=

Las Bases de datos son relaciones y PHP5/Kumbia es orientado a objetos por lo tanto deberíamos acceder a las BD en forma orientada a objetos. Para esto necesitamos una interfaz que transforme la lógica de objetos a la relacional y viceversa. Este proceso es llamado mapeo objeto-relacional o en inglés ORM (Object-Relational Mapping), y es usado por Kumbia en su arquitectura MVC. 

Se trata de dar a los objetos, acceso a los datos sin dejar de lado las reglas de la lógica de negocios. 

Un beneficio de la capa da abstracción objeto/relacional es que previene un poco el uso de sintaxis específica de un motor de base de datos, ya que automáticamente traduce los llamados a los objetos modelos en instrucciones SQL optimizadas para el motor actual. 

Esto significa que cambiar de un motor de base de datos a otro en la mitad del proyecto es más fácil de lo que se imagina. Pasar de PostgreSQL a MySQL o a Oracle requiere de un cambio de una línea de configuración. 

Una capa de abstracción encapsula la lógica de datos. El resto de la aplicación no necesita saber sobre instrucciones SQL, aunque puede hacerlo si lo requiere. 

Ver las filas como objetos y las tablas como clases tiene otro beneficio. Permiten crear nuevos accesos para nuestras tablas. Por ejemplo si tenemos una clase Clientes y tiene un campo primer nombre, otro segundo nombre y apellidos entonces podemos crear un acceso llamado getNombre así: 

<source lang=php line>
public function getNombre(){
     return  $this->primer_nombre.” “.$this->segundo_nombre.” “.
     $this->apellidos;
}
</source>

Kumbia proporciona una serie de clases (ActiveRecord y SessionRecord) que permiten realizar este mapeo y además ejecutar operaciones nativas sobre las relaciones de la base de datos de forma más humana y entendible. 

= Capa de Abstracción Independiente en Kumbia=

Kumbia posee una primera capa que evita la reescritura del código que accede a bases de datos en caso de cambiar de un motor a otro. Posee todas las funciones básicas para efectuar operaciones sobre tablas, mantener conexiones, ejecutar consultas, etc. sin perder independencia. Esta capa funciona bajo la capa objeto relacional y es ampliamente usada por todo el framework. Debería ser usada en caso de necesitar un acceso de bajo nivel a la base de datos. 

Otra ventaja es que cursores y streams de conexión son encapsulados en objetos evitando escribir código repetitivo. 

= Adaptadores Kumbia =

Mientras estos adaptadores estén disponibles se puede tener acceso a un motor de base de datos en particular. Actualmente existen: MySQL, PostgreSQL (Beta) y Oracle (beta).

= Esquema de Acceso a BB.DD en Kumbia =

= Modelos =
La segunda capa de abstracción de datos utiliza un mapeo objeto/relacional para representar las entidades del modelo de datos en nuestras aplicaciones. Estos modelos son parte integral de la arquitectura MVC (Model View Controller) y están basados en el patrón ActiveRecord. 

==Características de los modelos: ==
Implementan las clases de la capa de negocios: Productos, Clientes, Facturas, Empleados, etc. 
Mantienen los datos y su lógica juntos: Un producto tiene una cantidad y se vende sólo si está activo.
Representar relaciones en el modelo: Una Cliente tiene muchas Facturas

== Acceso Directo a RDBMS ==

===La Clase DdBase===

La clase “DbBase” personalizada para cada motor es cargada automáticamente y está disponible globalmente. El valor database.type en config/environment.ini, indica qué driver se debe cargar automáticamente. 

Crear una instancia de DdBase

Ya que los parámetros de conexión de la base de datos están definidos en config/environment.ini podemos utilizar esta función para crear el objeto db. 

Ejemplo: 

 <source lang=php line>
 <?php
    $db = DbBase::raw_connect();
 ?>
 </source>

===Propiedades de la Clase DB ===

====$db->Id_Connection====

Posee una referencia al stream de conexión a la base de datos 

====$db->dbUser====

Usuario de la base de datos utilizado para crear la conexión 

====$db->dbPass ====

Password del Usuario de la base de datos utilizado para crear la conexión 

====$db->dbHost ====

Host de la base de datos utilizado para crear la conexión 

====$db->dbName ====

Nombre de la base de datos actual 

====$db->dbPort==== 

Puerto de la base de datos utilizado para crear la conexión 

====$db->lastError ====

Último error generado por el motor de la base de datos producido en alguna operación SQL. 

====$db->lastResultQuery ====

Ultima sentencia SQL ejecutada en la base de datos en la instancia 

===Métodos de la Clase DB ===

====connect()====

Descripción: Permite crear o reestablecer una conexión con el motor de base de datos. 

Sintaxis: 

$db->connect([string $host], [string $user], [string $password], [string $database_name])

====query()====

'''Descripción:'''

Permite enviar sentencias SQL al motor de base de datos. El parámetro debug permite ver un mensaje del SQL que es enviado al motor de base de datos. 

'''Sintaxis: '''

$db->query(string $sql, [bool $debug=false])

'''Ejemplo: '''

<source lang=php line>
<?php
   $db = db::raw_connect();
   $db->query(“update clientes set estado = ‘A’”);
   $db->close();
?>
</source>

====close()==== 

'''Descripción:''' 

Cierra la conexión encapsulada en el objeto 

'''Sintaxis:''' 

<source lang=php line>
$db->close()
</source>

====fetch_array()====

'''Descripción: '''

Recorre el cursor ejecutado en la última operación select. 

'''Sintaxis: '''

<source lang=php line>
$db->fetch_array([cursor $cursor], [int $tipo_resultado=DB_BOTH])
</source>

'''Ejemplo:''' 

<source lang=php line>
<?php
   $db = db::raw_connect();
   $db->query(“select codigo, nombre from productos”);
   
   while($producto = $db->fetch_array()){
       print$producto[‘nombre’];
   }//fin while
    
   $db->close();
?>

Los tipos de resultado pueden ser: 

db::DB_ASSOC: Array con índices asociativos de los nombres de los campos.
db::DB_NUM: Array con índices numéricos que indican la posición del campo en el select.
db::DB_BOTH: Array con índices tanto numéricos como asociativos.

====num_rows()==== 

'''Descripción:'''

Devuelve el número de filas de la última instrucción select enviada al motor de base de datos. 

'''Sintaxis:''' 

<source lang=php line>
$db->num_rows([cursor $cursor]); 
</source>

'''Ejemplo:'''

<source lang=php line>
<?php
    $db = db::raw_connect;
    $db->query(“select codigo, nombre from productos”);
   print “Hay  ”.$db->num_rows().“ productos “;
    $db->close();
?>
</source>

====field_name()====

'''Descripción:'''

Devuelve el nombre del campo en la posición $number del último select enviado al motor de base de datos. 

'''Sintaxis:''' 

<source lang=php line>
$db->field_name(int $number, [cursor $cursor]);
</source>

====data_seek()====

'''Descripción:'''

Se mueve a la posición $number del cursor de la última instrucción select enviada al motor de base de datos. 

'''Sintaxis:''' 

<source lang=php line>
$db->data_seek(int $number, [cursor $cursor]);
</source>

====affected_rows()====

'''Descripción:'''

Devuelve el número de filas afectadas en la última instrucción insert, update o delete. 

'''Sintaxis:''' 

<source lang=php line>
$db->affected_rows();
</source>

====error()====

'''Descripción: '''

Devuelve la cadena descriptiva del último error generado por base de datos producido por la última instrucción SQL. 

'''Sintaxis:'''
<source lang=php line>
 $db->error();
</source>

====no_error()====

'''Descripción:'''

Devuelve el número interno del último error generado por base de datos producido por la última instrucción SQL. 

'''Sintaxis: '''

<source lang=php line>
$db->no_error();
</source>

====find()====

'''Descripción:'''

Ejecuta un Select en el motor con los parámetros enviados y devuelve un Array con los resultados. 

'''Sintaxis:'''

<source lang=php line>
$db->find(string $table, [string $where=”1=1”], [string $fields=”*”], [string $orderBy=”1”]);
</source>

'''Ejemplo: '''

<source lang=php line>
<?php
   $db = db::raw_connect();
   foreach($db->find(“productos”) as $producto){
       print $producto[‘nombre’];
   } //fin del foreach 
   $db->close();
?>
</source>

====in_query()====

'''Descripción:'''

Devuelve el resultado de una instrucción SQL en un array listo para ser recorrido. 

'''Sintaxis: '''
<source lang=php line>
$db->in_query(string $sql, [bool $debug=false], [int $tipo_resultado = db::DB_BOTH]);
</source>

'''Ejemplo:''' 

<source lang=php line>
<?php
   $db = db::raw_connect();
   foreach($db->in_query(“select * from productos”) as $producto){
      print $producto[‘nombre’];
   }//fin del foreach 
   $db->close(); 
?>
</source>

====in_query_assoc()==== 

'''Descripción:'''

Devuelve el resultado de una instrucción SQL en un array con indexado asociativo listo para ser recorrido. 

'''Sintaxis:''' 
<source lang=php line>
$db->in_query_assoc(string $sql, [bool $debug=false]);
</source>

====in_query_num()====

'''Descripción:'''

Devuelve el resultado de una instrucción SQL en un array con indexado numérico listo para ser recorrido. 

'''Sintaxis:'''

<source lang=php line>
$db->in_query_num(string $sql, [bool $debug=false]);
</source>

====fetch_one()====

'''Descripción:'''

Devuelve la primera fila de un select . Es útil cuando el select devuelve una sola fila 

'''Sintaxis:''' 
 <source lang=php line>
 $db->fetch_one(string $sql, [bool $debug=false]);
 </source>

'''Ejemplo:'''
 <source lang=php line>
 <?php
     $db = db::raw_connect();
     $producto = $db->fetch_one(“select * from producto where codigo = 1”);
     print $producto[‘nombre’];
     $db->close();
 ?>
 </source>

====table_exists()====

Descripción: Devuelve verdadero si la tabla $table existe en la base de datos, falso de lo contrario. 

Sintaxis: 
 <source lang=php line>
 $db->table_exists(string $table);
 </source>