Edición de «KumbiaPHP Framework Versión 1.0 Spirit»

== Introducción ==
En la versión [https://launchpad.net/kumbia/0.5.1 0.5.1] el enfoque primordial que ha considerado el [https://launchpad.net/%7Edesarrollokumbia Equipo de Desarrollo] gira en torno al rendimiento del framework a nivel de velocidad y en este sentido hemos obtenido grandes resultados, de manera que las pruebas en base a esta versión nos indica que es bastante rápida con pequeños cambios aplicando las mejores practicas de desarrollo.

Entre los componentes a nivel del core que hemos tocado para lograr nuestros objetivos se encuentran:
#environment.ini
#Router
#Dispatcher
#Clase Kumbia
#Vistas
##Templates, Layouts y Partials
##Helpers
#Logger
#config.ini
#Cache


Como se menciona al principio muchos de estos cambios son a nivel de '''core''', esto significa que haremos pocas adecuaciones para migrar nuestras aplicaciones que hayan sido desarrolladas con la [https://launchpad.net/kumbia/0.5 versión 0.5] para llevarlas hasta la [https://launchpad.net/kumbia/0.5.1 versión 0.5.1], esto con la finalidad de garantizar compatibilidad entre versiones.

== Migración Rápida ==
En esta sección se explica de forma rápida y sencilla como migrar nuestras aplicaciones de la versión [https://launchpad.net/kumbia/0.5 0.5] a la [https://launchpad.net/kumbia/0.5.1 0.5.1] en las próximas secciones se explican en detalle los cambios.
#En los controladores cambiar el atributo '''$template''' por '''$layout'''.
#Si haz modificado el archivo '''views/index.phtml''' este fue ubicado en el directorio '''views/templates/index.phtml''', es decir que lo debes sobreescribir o aplicar los cambios que quieras.
#Para inicializar tu aplicación es mejor utilizar el archivo '''config/routes.ini''' agregando una regla de enrutamiento estático, por ejemplo.
 ;con esta regla cada vez que inicie la aplicación http://localhost/kumbia/ irá hacia un controlador admin y una acción autenticar
 / = admin/autenticar
Esto sustituye editar el archivo '''apps/default/controllers/application.php''' en su acción '''init()''', solo se ha de agregar en el '''routes.ini''' la ruta que hacemos en el método '''init()'''
#Si utilizas '''Partials'''

== Estructura del archivo ./config/environment.ini ==

En este archivo se hace un cambio donde no se verán afectado nuestro desarrollo habitual ya que se decidió  quitar el prefijo '''database''' esto porque se noto que se consumía tiempo innecesario en el procesamiento de este archivo, quedando de la siguiente forma.

<pre>
; Kumbia Web Framework Configuration
; Parámetros de base de datos
; Utiliza el nombre del controlador nativo (mysql, pgsql, oracle)
; Coloca pdo = On si usas PHP Data Objects

[development]
host = localhost
username = root
password =
name = innogest
type = mysql

[production]
host = localhost
username = root
password =
name = test
type = mysql</pre>

== Router ==
Mejoras de Rendimiento.

== Dispatcher ==
Mejoras de Rendimiento.

== Clase Kumbia ==
Mejoras de Rendimiento.

== Vistas ==
[[Imagen:Views.jpg|Estructura de Vistas|right|frameless|300px]]
Kumbia posee un sistema de presentación basado en Vistas (Views) que viene siendo el tercer componente del sistema [http://es.wikipedia.org/wiki/Modelo_Vista_Controlador MVC], el framework permite mediante plantillas que son reutilizables para no repetir código.

Las vistas deberían contener una cantidad mínima de código en PHP para que fuese suficientemente entendible por un diseñador Web y además, para dejar a las vistas sólo las tareas de visualizar los resultados generados por los controladores y presentar las capturas de datos para usuarios.

En la '''versión 0.5.1''' se incorporan dos(02) nuevos directorios en el directorio de vistas de nuestra aplicación los cuales son:
#views/templates/
#views/partials/

=== views/templates/ ===
Los [http://en.wikipedia.org/wiki/Template_(file_format) Template] son un tipo de archivo pre-formateado utilizado como base para otros archivos.

En este directorio esta la capa mas externa de nuestras vistas, para aclarar esta idea en esta es donde se coloca la estructura del documento XHTML (doctype, html, head, etc) en la forma como se trabaja en la '''versión 0.5''' esto es representado por el archivo '''views/index.phtml''' de esta forma no existe una flexibilidad de manera que podamos cambiar ese template, en la '''versión 0.5.1''' se crea un directorio '''views/templates/''' por defecto existe el archivo '''index.phtml''' pero podemos podemos agregar cuantos se desee y poderlo cambiar desde nuestro controlador de la siguiente forma:
 
 class PruebaController extends ApplicationController 
 {
     public $template = 'plantilla';
 }

El atributo '''$template''' existe en la super clase '''Controller''' y tiene un valor por defecto (index) esto significa que el sistema de plantillas del framework buscara dentro de directorio views/templates/ el valor que le demos, por defecto buscara '''index.phtml''' pero en otro caso que veamos conveniente podria ser otro template tal como se muestra en el ejemplo seria '''plantilla.phtml'''

=== views/partials/ ===
Los partials ([http://es.wikipedia.org/wiki/Widget#Los_widget_en_el_.C3.A1mbito_de_la_programaci.C3.B3n_gr.C3.A1fica widget]) son pequeñas vistas que pueden incluirse dentro de otra vista para evitar repetir código, en la '''versión 0.5''' la convención que se tiene es que ha comenzar el nombre del archivo con un underscore(_) ejemplo, '''_partials.phtml''' y estar dentro del directorio de vistas de controlador que lo invoca, en la '''versión 0.5.1''' con la finalidad de ofrecer mayor flexibilidad en el manejo de las vistas se ha creado el directorio '''views/partials/''' donde se han de colocar los partials con esto quitamos la convención de los nombres de los partials, de igual forma ya no se encuentran atados a los controladores tal como pasaba en la '''versión 0.5'''.
Los partiasl pueden representar cualquier tipo de [http://es.wikipedia.org/wiki/GUI Interfaz de Usuario], importante destacar que los partials pueden ser renderizados (mostrados) desde cualquier nivel de vista donde lo necesitemos.

Ejemplo:

'''views/partials/fecha.phtml'''
<pre>
 <div style='background: #333eee; padding: 15px 10px 15px 10px; text-align: center'>
       <i><?php echo date('Y-m-d'); ?></i>
 </div>
</pre>
Como se aprecia este partials solo mostrará la fecha actual cuando sea invocado, pero como se menciono antes puede contener cualquier información para el usuario, pero aun falta hacer un llamado a este partials para que el mismo sea mostrado este llamado puede ser desde cualquier nivel del sistema de plantilla que ofrece el fremawork y basta con hacer en la vista (Templates, Layouts, views) lo siguiente.

<pre>
 <?php render_partial('fecha') ?>
</pre>


Describiendo la función de manera mas detallada:
<pre>
render_partial($partial, $time=false, $params=array())
</pre>

Para cachear los partials, el tiempo de cacheo debe indicarse con el formato de strtotime tal como lo utiliza el componente cache.

<pre>
 <?php render_partial('fecha', '+4 days') ?>
</pre> 

Si no se desea cachear, se indica como segundo argumento "false", el cual es el valor por defecto

<pre>
 <?php render_partial('fecha', false) ?>
</pre> 

También es posible pasar variables al partial utilizando parámetros con nombre o utilizando como argumento un array. Si estos parámetros son se pasan en forma de array soporta cualquier tipo de dato (objecto, array, etc).

<pre>
 <?php render_partial('fecha', false, 'var: valor') ?>
</pre> 

<pre>
 <?php render_partial('fecha', false, array('var' => 'valor')) ?>
</pre> 

Y esta es accesible en el partial como $var

Los modelos ya no se cargan directamente en los partials, esto mejora la velocidad, para hacer uso de los modelos en los partials, el usuario puede instanciar directamente el modelo, la desventaja de esta manera es que el usuario debe haber cargado previamente el modelo haciendo uso de "load_models" en el controller en caso de utilizar carga selectiva de modelos:

<pre>
 <?php 
    $Usuario = new Usuario();
    $usuario = $Usuario->find(1);
 ?>
</pre>

También es posible utilizar el método '''Kumbia::model($model)''', el cual se encarga de cargar la clase de ser necesario y maneja un singleton del objeto, este metodo solo debe usarse para obtener un modelo para efectuar consultas de recuperación de datos (find, findBy, find_first, etc) preferiblemente.

<pre>
 <?php $usuario = Kumbia::model('Usuario')->find(1); ?>
</pre>

== Logger ==
La clase Logger para el manejo de [http://es.wikipedia.org/wiki/Log_(registro) Log] fue reescrita de forma estática, esto quiere decir ya no es necesario crear una instancia de la clase Logger. Esta clase dispone de una variedad de métodos para manejar distintos tipos de Log.
<pre>
 <?php Logger::error('Mensaje de Error')?>
</pre>
La salida de la instrucción anterior será lo siguiente:
<pre>[Thu, 05 Feb 09 15:19:39 -0500][ERROR] Mensaje de Error</pre>
Por defecto los archivos log tienen el siguiente nombre '''logDDMMYYY.txt''' este nombre puede ser cambiado si así lo deseamos a través de un parámetro adicional al método.
<pre>
 <?php Logger::error('Mensaje de Error', 'mi_log')?>
</pre>
Se puede apreciar el segundo parámetro ahora el archivo tendrá como nombre '''mi_log.txt'''
=== Métodos de la Clase Logger ===

Logger::warning ($msg);

Logger::error ($msg)

Logger::debug ($msg)

Logger::alert ($msg)

Logger::critical ($msg)

Logger::notice ($msg)

Logger::info ($msg)

Logger::emergence ($msg)

Logger::custom ($type='CUSTOM', $msg)
== Config.ini ==
Se agrega una opción en este archivo para cuando se necesite trabajar con el framework pero sin interactuar con una Base de Datos, en la versión 0.5 esto no era posible siempre había que colocar unos datos de conexión.
<pre>
;; Configuracion de Aplicaciones

; Explicación de la Configuración:

; default_app: es la aplicacion por defecto
; mode: Es el entorno en el que se esta trabajando que esta definido en config/config
; name: Es el nombre de la aplicación
; timezone: Es la zona horaria que usará el framework
; interactive: Indica si la aplicación se encuentra en modo interactivo
; controllers_dir: Indica en que directorio se encuentran los controladores
; models_dir: Indica en que directorio se encuentran los modelos
; views_dir: Indica en que directorio se encuentran las vistas
; helpers_dir: Indica en que directorio se encuentran los helpers de usuario
; dbdate: Formato de Fecha por defecto de la Applicación
; charset: codificacion de caracteres
; databases: Habilita la carga de modelos
; models_autoload: Habilita la autocarga de modelos
; metadata_lifetime: Tiempo de vida de la metadata cacheada
; locale: Localicazion


; ¡¡¡ ADVERTENCIA !!!
; Cuando se efectua el cambio de mode, a production, es necesario eliminar
; el contenido del directorio de cache de la aplicacion para que se renueve
; la metadata


[kumbia]
default_app = default
timezone = "America/New_York"

[default]
mode = development
name = "KUMBIA PROJECT"
interactive = On
controllers_dir = default/controllers
models_dir = default/models
views_dir = default/views
plugins_dir = default/views
helpers_dir = default/helpers
dbdate = YYYY-MM-DD
debug = On
log_exceptions = On
charset = UTF-8
databases = off
models_autoload = On
;metadata_lifetime = "+1 year"
;locale = es_ES
</pre>

Se puede apreciar el nuevo atributo '''databases = off''' por defecto ese sera el valor (off), si se necesita trabajar con BD solo hay que cambiarle el valor a '''On''' para que el framewok cargue los modelos.

==Cache==
El componente cache fué mejorado y ahora posee una implementación estática, para hacer uso de la cache es necesario tener permisos de escritura en el directorio "cache". Los métodos de la clase Cache son los siguientes:

===Cache::get($id, $group='default')===
Obtiene los datos cacheados. Los elementos cacheados pueden agruparse en grupos, lo cual permite evitar colisiones entre elementos cacheados con igual $id.

string '''$id''': identificador del elemento cacheado<br>
string '''$group''': grupo al cual pertenece el elemento cacheado (por defecto "default")

<pre>
$data = Cache::get('data');
</pre>

===Cache::save($value, $lifetime=null, $id=false, $group='default')===
Guarda los datos a cachear.

mixed '''$value''': valor a cachear (automaticamente es serializado antes de guardar)<br>
string '''$lifetime''': tiempo de vida de los datos (formato de [http://fr.php.net/manual/es/function.strtotime.php strtotime]), si es null, los datos no expiran nunca.<br>
string '''$id''': identificador del elemento a almacenar, si no se especifica, se toma el id y grupo del ultimo get efectuado<br>
string '''$group''': grupo al cual pertenece

<pre>
<?php if($data = Cache::get('data')): ?>
    <?php echo $data ?>
<?php else: ?>
    <?php ob_start() ?>
    Hola
    <?php 
        $data = ob_get_contents();
        Cache::save($data, '+21 days');
        ob_end_flush();        
    ?>
<?php endif; ?>    
</pre>

<pre>
Cache::save('hola', null, 'data');
$data = Cache::get('hola');
</pre>

Nota: el grupo "kumbia.*" esta reservado para el uso exclusivo de Kumbia.

===Cache::start($lifetime, $id, $group='default')===
Cachea capturando el buffer de salida, se debe utilizar en conjunto a "Cache::end()" para terminar la captura, si el elemento esta cacheado entonces lo retorna.

string '''$lifetime''': tiempo de vida de los datos (formato de strtotime), si es null, los datos no expiran nunca.<br>
string '''$id''': identificador del elemento a almacenar, si no se especifica, se toma el id y grupo del ultimo get efectuado<br>
string '''$group''': grupo al cual pertenece

<pre>
<?php if($data = Cache::start('+1 day','data')): ?>
    <?php echo $data ?>
<?php else: ?>
    Hola
    <?php Cache::end()?>
<?php endif; ?>    
</pre>

===Cache::end()===
Guarda los datos en la cache tomados del buffer de salida.

===Cache::clean($group=false)===
Limpia la cache. Si no se indica grupo limpia toda la cache.

<pre>
Cache::clean('default');
</pre>

===Cache::remove($id, $group='default')===
Elimina un elemento específico de la cache

<pre>
Cache::remove('data');
</pre>

===Cache::active($active)===
Activa el uso de la cache

<pre>
Cache::active(true);
</pre>

==ActiveRecord==
Ahora se ha definido una forma concreta para el paso de parametros en los validadores y asimismo se adicionaron parametros para personalizar los mensajes de error.

===validates_uniqueness_of($field, $params=array())===
Valida que el campo sea unico

string '''$field''': campo a validar<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_uniqueness_of('cedula', 'message: La cedula ya existe')
$this->validates_uniqueness_of('cedula', array('message'=>'La cedula ya existe'))
</pre>

===validates_date_in($field, $params=array())===
Valida que el campo sea tipo fecha

string '''$field''': campo a validar<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_date_in('fecha', 'message: Fecha invalida')
$this->validates_date_in('fecha', array('message'=>'Fecha invalida'))
</pre>


===validates_presence_of($field, $params=array())===
Valida que el campo no sea nulo

string '''$field''': campo a validar<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_presence_of('fecha_opt', 'field: Fecha')
</pre>


===validates_length_of($field, $max, $min=0, $params=array())===
Valida que el campo no sea nulo

string '''$field''': campo a validar<br>
int '''$max''': valor maximo<br>
int '''$min''': valor minimo<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
too_long: mensaje a mostrar cuando sea muy largo<br>
too_short: mensaje a mostrar cuando sea muy corto<br>
field: nombre del campo

<pre>
$this->validates_length_of('nombre', '25')
$this->validates_length_of('nombre', '25', 0,'too_long: Nombre muy largo')
$this->validates_length_of('nombre', '25', 0,array('too_long'=>'Nombre muy largo'))
</pre>


===validates_inclusion_in($field, $list, $params=array())===
Valida que el campo este incluido en los valores de la lista

string '''$field''': campo a validar<br>
array '''$list''': lista de elementos<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_inclusion_in('seleccion', array('a', 'b'))
</pre>


===validates_exclusion_of($field, $list, $params=array())===
Valida que el campo no este incluido en los valores de la lista

string '''$field''': campo a validar<br>
array '''$list''': lista de elementos<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_exclusion_of('seleccion', array('a', 'b'))
</pre>

===validates_format_of($field, $pattern, $params=array())===
Valida que el campo coincida con el patron indicado

string '''$field''': campo a validar<br>
array '''$pattern''': expresion regular compatible con perl<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_format_of('seleccion', '/^\d{3}[A-Z]/')
</pre>

===validates_format_of($field, $pattern, $params=array())===
Valida que el campo coincida con el patron indicado

string '''$field''': campo a validar<br>
array '''$pattern''': expresion regular compatible con perl<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_format_of('seleccion', '/^\d{3}[A-Z]/')
</pre>


===validates_numericality_of($field, $params=array())===
Valida que el campo sea numerico

string '''$field''': campo a validar<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_numericality_of('cedula')
</pre>


===validates_email_in($field, $params=array())===
Valida que el campo sea un correo electronico

string '''$field''': campo a validar<br>
array '''$params''': array de parametros con nombre

Parametros con nombre:<br>
message: mensaje a mostrar<br>
field: nombre del campo

<pre>
$this->validates_email_in('email')
</pre>


==Modos de la Aplicación==
La aplicación dispone de dos modos de ejecución el cual es indicado en el config.ini, estos se describen a continuación:

===Production===
Indicando en el config.ini "mode = production", se entra en el modo de producción, en este la cache de kumbia esta activada y se cachea información necesaria para agilizar la carga de la aplicación tal como la metadata de la base datos (información de tablas y campos), asimismo las vistas que el usuario desee cachear. 

===Development===
Indicando en el config.ini "mode = development", se entra en el modo de desarrollo, en este la cache de kumbia esta desactivada y cualquier cambio que se haga en los campos y tablas de la base de datos (adicion de campos, etc), vistas de la aplicación que se cacheen, surtiran efecto inmediatamente.

La cache de kumbia se puede activar nuevamente utilizando el metodo active de la clase Cache.

<pre>
Cache::active(true);
</pre>

'''Cuando se cambia de modo development a modo production, es necesario limpiar la cache de kumbia para que se pueda renovar los nuevos metadatos y vistas, esto se hace facilmente eliminando el contenido del directorio de cache para la aplicación, en el caso de la aplicación por defecto sería el directorio cache/default.'''

== Carga selectiva de modelos ==
En la versión [https://launchpad.net/kumbia/0.5.1 0.5.1] se puede cargar solo los modelos que el controlador requiera, de esa manera se optimiza los procesos de la aplicación y consume menos recursos. Para utilizar la carga selectiva, es conveniente deshabilitar la autocarga de modelos en el config.ini con "models_autoload = Off".

Para cargar los modelos en el controlador se utiliza el metodo "load_models"

<pre>
class UsuarioController extends ApplicationController {
  public function index()
  {
    $this->load_models('Usuario', 'DatosPersonales');
  }
}
</pre>

Asimismo se puede indicar con el atributo de controlador $models.

<pre>
class UsuarioController extends ApplicationController {
  public $models = array('Usuario', 'DatosPersonales');
  
  public function index()
  {
  }
}
</pre>