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

"Hemos llamado Spirit a la versión 1.0 porque Spirit, [http://es.wikipedia.org/wiki/Spirit nuestro robot de Marte], tiene como características principales, fuerza y velocidad. Fuerza, porque su comunidad cada vez mas grande hace que nuestro framework KumbiaPHP avance a pasos agigantados. Velocidad, porque nuestro core team que pertenece a otro planeta, continuamente esta aplicando las ultimas técnicas y haciendo que otros framework's se queden atrás día a día. En definitiva Spirit, hace que tus aplicaciones vuelen, resulten mas atractivas y fáciles de mantener."

  ;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

extensions = kumbia.logger, kumbia.auth

libs = logger, auth

 

== Constante en KumbiaPHP==

En la version 1.0 Spirit, se ha creado tres constantes cada cual cumple un objetivo especifico con el fin de brindar mayor flexibilidad al momento de manejar rutas (paths) en el framework.

 

Constante que contiene la ruta absoluta al directorio donde se encuentra nuestra aplicación (app).

 

echo APP_PATH; //la salida es: /var/www/kumbiaphp/app/ 

 

Esta constante es posible utilizarla para incluir archivos que se encuentre bajo el arbol de directorio de la aplicación, por ejemplo imagine que quiere incluir un archivo que esta en el directio '''app/libs/test.php''' la forma de hacerlo seria.

  include_once APP_PATH.'libs/test.php';

 

'''NOTA: siempre será mejor utilizar el [[KumbiaPHP_Framework_Versión_1.0_Spirit#Carga_Selectiva.2C_Inyecci.C3.B3n_de_Dependencias_y_el_Componente_Load |Componente Load]] para incluir dependencias.'''

 

Constante que contiene la ruta absoluta al directorio donde se encuentra el [[KumbiaPHP_Framework_Versión_1.0_Spirit#Explicando_dir_core.2F |core]] de KumbiaPHP.

 

 

 

'''NOTA: El core de KumbiaPHP en la version 1.0 esta totalmente desacoplado del directorio de la aplicación. [[KumbiaPHP_Framework_Versión_1.0_Spirit#Ventajas_de_esta_nueva_estructura_de_directorios|Ventajas de la Estructura de directorio]]'''

 

Constante que contiene la URL para el navegador (browser) y apunta a '''app/public/''' para enlazar imágenes, CSS, JavaScript y todo lo que sea ruta para browser.

 

 

//Enlaza una imagen que esta en public/img/imagen.jpg

<img src="<?php echo PUBLIC_PATH ?>img/imagen.jpg" alt="Una Imagen" />

 

//Enlaza el archivo CSS en public/css/style.css

 

 

 

|-- app

|  |-- application.php

|  |-- config

|  |-- controllers

|  |-- index.php

|  |-- tests

|  |-- vendors

|extensions||En este directorio se ubican las extensiones para nuestra aplicación, una extensión te permite adicionar nuevas características que serán utilizadas e integradas a la aplicación por medio de las librerías que proporciona [http://www.kumbiaphp.com KumbiaPHP]

Como se aprecia en la imagen existe una estrecha relación entre '''application.php''' y los controladores disponibles en el directorio controllers/. Esta relación se basa principalmente en que las variables y métodos creados en el '''ApplicationController''' (application.php) estarán disponibles para ser usados en cualquier controlador que tengamos en nuestra aplicación.

*'''locale''' Localización.

; locale: Localizacion

password = 1qaz2WSX

name = test

password = 1qaz2WSX

type = mssql

password = 1qaz2WSX

type = mssql

En este archivo fue eliminado, ahora se recomienda la carga explicita con '''require''' o '''include''' o en su defecto aprovechar la autocarga de librerias de KumbiaPHP.

O mejor usar el Load::lib('lib')

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 <s>versión 0.5</s> esto es representado por el archivo <s>'''views/index.phtml'''</s> de esta forma no existe una flexibilidad de manera que podamos cambiar ese template, en la [https://launchpad.net/kumbia/1.0 versión 1.0] se crea un directorio '''views/templates/''' por defecto existe el archivo '''default.phtml''' pero podemos agregar cuantos se desee y poderlo cambiar desde nuestro controlador de la siguiente forma:

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 framework, en la'''versión 0.5''' se hacia uso de la funcion "render_partial", sin embargo con la finalidad de obtener mayor orden e intuitividad, esta función se encapsulo en la clase '''View''',  y basta con hacer en la vista (Templates, views) lo siguiente.

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

Con la intención de ofrecer mayor comodidad, KumbiaPHP también hace posible obtener una instancia de un modelo directamente haciendo uso del método '''[[KumbiaPHP_Framework_Versión_1.0_Spirit#Load::model.28.24model.29 |Load::model($modelo)]]'''.

Su uso para las vistas de las acciones esta íntimamente ligado a los '''echo''' o '''print''' que efectué el usuario, asimismo determina el lugar donde se mostrarán los mensajes '''Flash''' provenientes de ActiveRecord o los propios. Ejemplo:

Un '''''helpers''''' representa una ayuda a nivel de las vistas (view), esto quiere decir siendo consistente con el m'''V'''c solo deben ser utilizados en las vistas.

=== Utilizando el método render($view, [$template]) ===

Este es un método que es muy poderoso con una utilización correcta del mismo, en la versión 1.0 lo hemos extendido para ofrecer mas flexibilidad en el manejo de las vistas, el cual nos permite de forma dinámica poder cambiar un view y un [[#views.2Ftemplates.2F | Template]] (el template es opcional) esto nos permite tener varias vistas (views) para la misma action incluso varios [[#views.2Ftemplates.2F | Template]].

Esto es una de las ventajas del manejo de vistas de [http://www.kumbiaphp.com KumbiaPHP] y nos sirve para muchas cosas. Por ej: Si tenemos una aplicación web y también se quiere que esta pueda ser accedida desde dispositivos móviles (celular, PDA, etc.) no es necesario programar toda la aplicación de nuevo, sino que simplemente se cambia la vista pero lo mas importante es que el controlador sigue siendo el mismo.

'''NOTA: KumbiaPHP muestra el view con el mismo nombre de la acción.'''

    public function saludo($var=null)

'''app/views/blog/saludo.phtml'''  (vista por defecto de la acción).

  <?php echo "Bienvenido $usuario" ?>

La vista anterior se renderizara (mostrar) cuando tengamos la siguiente URL:

  http://dominio.com/blog/saludo/

'''app/views/blog/adios.phtml'''  (vista cuando existe el parámetro).

<source lang=php>

  <?php echo "Adios $usuario" ?>

La vista anterior se renderizara (mostrar) cuando tengamos la siguiente URL:

  http://dominio.com/blog/saludo/adios/

===== Cambiando el Template con método render($view, $template) =====

Pero también es posible cambiar el [[#views.2Ftemplates.2F | Template]] veamos la misma acción pero ahora cambiara el template.

<?php

     public function saludo($var=null)

     {

         $this->usuario = 'Usuario';

    if($var == 'adios'){

            $this->render('adios', 'otro_template');

     }

    public function saludo($var=null)

        $this->usuario = 'Usuario';

    if($var == 'adios'){

            $this->render('adios', null);

Cuando vayan a http://dominio.com/blog/saludo/adios/ KumbiaPHP cargara solamente el view adios.phtml sin template ya que así lo indicamos.

===== Ahora sin view render(null, [$template]) =====

Ahora indicamos que no deseamos mostrar el View de la acción, veamos la misma acción pero sin el view.

<?php

    public function saludo($var=null)

     {

        $this->usuario = 'Usuario';

            Flash::notice('Adios '.$this->usuario);

            $this->render(null);

===== Ahora sin view y sin template render(null, null) =====

Ahora indicamos que no deseamos mostrar el View de la acción y el Template, veamos la misma acción pero sin el view y sin template.

            return Router::route_to('controller: otro_controller');

== 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.

<?php Logger::error('Mensaje de Error')?>

<pre>[Thu, 05 Feb 09 15:19:39 -0500][ERROR] Mensaje de Error</pre>

<?php Logger::error('Mensaje de Error', 'mi_log')?>

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)

El componente cache fué mejorado y ahora posee una implementación utilizando los patrones de diseño factory y singleton, para hacer uso de la cache es necesario tener permisos de escritura en el directorio "cache" (para el caso de los manejadores "sqlite" y "file").

 

===Cache::driver($driver=null)===

 

Ejemplos:

$data = Cache::driver()->get('data');

 

$data_memcache = Cache::driver('memcache')->get('data');

 

$data_apc = Cache::driver('APC')->get('data');

Todos los manejadores de cache comparten métodos comunes indicados através de la clase abstracta '''Cache''' he implementados especificamente en cada manejador, los metodos de los manejadores de cache son los siguientes:

===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")

$data = Cache::driver()->get('data');

mixed '''$value''': valor a cachear (automaticamente es serializado antes de guardar)<br>

string '''$lifetime''': tiempo de vida de los datos (formato de [http://es2.php.net/manual/en/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>

<source lang=php>

<?php if($data = Cache::driver()->get('data')): ?>

    <?php echo $data ?>

<?php else: ?>

    <?php ob_start() ?>

        $data = ob_get_contents();

        Cache::driver()->save($data, '+21 days');

Cache::driver()->save('hola', null, 'data');

$data = Cache::driver()->get('data');

</source>

 

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

===start($lifetime, $id, $group='default')===

Cachea capturando el buffer de salida, se debe utilizar en conjunto a "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

<?php if($data = Cache::driver()->start('+1 day','data')): ?>

===clean($group=false)===

Limpia la cache. Si no se indica grupo limpia toda la cache.

<source lang=php>

Cache::driver()->clean('default');

Cache::driver()->remove('data');

==Cacheo automático de views y templates==

Ahora el cacheo de views y templates desde el controller se hará utilizando el método '''cache()'''.

Para cachear una vista desde la acción:

<pre>

$this->cache('+1 day');

<pre>

$this->cache('+1 day', 'template');

</pre>

$this->cache(false);

Ahora se ha definido una forma concreta para el paso de parámetros en los validadores y asimismo se adicionaron parámetros para personalizar los mensajes de error.

        $this->validates_uniqueness_of('cedula', 'message: La cedula ya existe');

===validates_uniqueness_of($field, $params=array())===

Valida que el campo sea único

field: nombre del campo (muestra un mensaje con el valor del campo)

 

$this->validates_uniqueness_of('cedula', 'message: La cedula ya existe')

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

 

===validates_date_in($field, $params=array())===

Valida que el campo sea tipo fecha

$this->validates_date_in('fecha', 'message: Fecha invalida')

$this->validates_date_in('fecha', array('message'=>'Fecha invalida'))

===validates_presence_of($field, $params=array())===

Valida que el campo no sea nulo

array '''$params''': array de parametros con nombre

Parametros con nombre:<br>

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

</source>

===validates_length_of($field, $max, $min=0, $params=array())===

Valida el tamaño mínimo y máximo de caracteres permitidos en el campo

string '''$field''': campo a validar<br>

int '''$max''': valor maximo<br>

int '''$min''': valor minimo<br>

array '''$params''': array de parametros con nombre

field: nombre del campo

$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'))

===validates_inclusion_in($field, $list, $params=array())===

array '''$list''': lista de elementos<br>

array '''$params''': array de parametros con nombre

Parametros con nombre:<br>

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

===validates_exclusion_of($field, $list, $params=array())===

array '''$list''': lista de elementos<br>

Parametros con nombre:<br>

message: mensaje a mostrar<br>

field: nombre del campo

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

===validates_format_of($field, $pattern, $params=array())===

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>

<source lang=php>

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

 

string '''$field''': campo a validar<br>

array '''$params''': array de parametros con nombre

 

$this->validates_email_in('email')

==Modos de una Aplicación==

===Production===

Indicando en el config.ini '''"production = Off"''', se entra en el modo de desarrollo, en este la cache de [http://www.kumbiaphp.com KumbiaPHP] esta desactivada y cualquier cambio que se haga en los campos y tablas de la base de datos (adición de campos, etc), vistas de la aplicación que se cacheen, surtirán efecto inmediatamente.

 

<source lang=php>

Load::lib('cache');

'''Cuando se cambia de modo, es necesario limpiar la cache que [http://www.kumbiaphp.com KumbiaPHP] ha creado para que se pueda renovar los nuevos metadatos y vistas, esto se hace simplemente eliminando el contenido del directorio de cache para la aplicación.'''

== Carga selectiva de modelos ==

==== Load::models($model) ====

Si la carga se efectúa en el controlador, automaticamente una instancia del modelo es cargada en un atributo del controlador correspondiente al nombre del modelo en notación camelcase.

''NOTA: El parámetro '''$model''' puede ser un directorio y/o archivo, en el caso de ser el archivo debe ser igual al nombre del mismo.''

<source lang=php >

  public function index()

    Load::models('usuario', 'datos_personales');

</source>

Asimismo se puede indicar con el atributo de controlador $models y estos serán cargados en cada acción.

<source lang=php >

  public $models = array('usuario', 'datos_personales');

Cargando un directorio de modelos

<source lang=php >

    /** se cargan los modelos en:  

    Load::models('dir', 'dir2/model1', 'model2')

</source>

'''NOTA: el nombre del modelo que recibe como parámetro este método debe ser pasado en notación smallcase'''

<source lang=php >

function pais_select($id, $value=null) {

    $Pais = Load::model('pais');

    foreach($Pais->find() as $pais) {

        $code .= "<option value=\"$pais->id\"";

            $code .= ' selected="selected"';

        $nombre = htmlspecialchars($pais->nombre);

        $code .= ">$nombre</option>";

    $code .= '</select>';

    return $code;

<source lang=php >

...

    //carga el modelo ubicado en models/dir/user.php

    Load::model('dir/user')->find();

    //carga el modelo ubicado en models/user_group.php

== Pages Controller ==

Es un nuevo controlador para el manejo de páginas estáticas (views estáticos), aunque se puede utilizar como cualquier otro controlador haciendo uso de los [[KumbiaPHP_Framework_Versión_1.0_Spirit#Vistas |Templates y Partials]].

Los parámetros pasados al método '''show()''' indican vistas que están en views/pages/  manteniendo su estructura de directorios

<source lang=php>

<?php echo link_to('pages/show/aviso', 'Ir Aviso') ?>

== Nuevo Helper ==

=== swf_tag($src) ===

Con este helper tendremos la posibilidad de agregar archivos flash a nuestras páginas de una manera fácil, rápida y sencilla, este helper utiliza una librería hecha en JavaScript y lo mejor de todo es que es Open Source, el helper object_tag("archivo.swf"), recibe como parámetro el nombre del archivo flash el cual debe estar ubicado en la carpeta public/swf, además de eso recibe parámetros por nombre como son "width", "height" y "wmode", el ancho y alto deben ser colocados para que el flash sea visible, de otra manera no se vera por las dimensiones. Veamos el siguiente ejemplo realizado en la vista '''index.phtml'''

<source lang="php" line>

<?php echo swf_tag("archivo.swf", "height: 300", "width: 300", "wmode: transparent") ?>

Este Helper nos garantiza que el código XHTML generado es validado por la W3C.

== Filter ==

=== Uso de Filter ===

El componente Filter, es un componente que permite filtrar y validar datos de una manera intuitiva, facil y simple.

Filter dispone de una serie de métodos estaticos que le permitirán filtrar los elementos indicados.

=== Filter::get($s, $options=array()) ===

'''$s (mixed)''': el valor a filtrar.

'''$options (array)''': array de configuración del filtro.

Los filtros se aplican al valor indicado.