KumbiaPHP Framework Versión 1.0 Spirit

Introducción

En la versión 1.0(antigua 0.5.1) el enfoque primordial que ha considerado el Equipo de Desarrollo gira en torno al rendimiento del framework a nivel de velocidad y mantenibilidad del framework en este sentido hemos desacoplado el core de kumbiaphp framework en una nueva estructura obteniendo grandes resultados, de manera que las pruebas en base a esta versión nos indica que vamos en buen camino y ademas es bastante rápida con los cambios aplicados siempre con las mejores practicas de desarrollo.

Entre los componentes a nivel del core que hemos tocado para lograr nuestros objetivos se encuentran:

1. Estructura de Directorios
2. environment.ini
3. Router
4. Dispatcher
5. Clase Kumbia
6. Vistas
   1. Templates y Partials
   2. Helpers
7. Logger
8. config.ini
9. 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 versión 0.5 para llevarlas hasta la versión 1.0(antigua 0.5.1), esto con la finalidad de garantizar compatibilidad entre versiones.

¿Por qué Spirit?

"Hemos llamado Spirit a la versión 1.0 porque 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."

Migración Rápida

En esta sección se explica de forma rápida y sencilla como migrar nuestras aplicaciones de la versión 0.5 a la versión 1.0(antigua 0.5.1) en las próximas secciones se explican en detalle los cambios.

• Con la nueva estructura de directorio migrar nuestras aplicaciones de la versión 0.5 es sumamente simple solo se ha copiar nuestra carpeta apps/default/ (donde estan los controllers, models, views, etc) hacia el directorio app/ de Nueva Estructura

• En el Controlador los métodos initialize, finalize, before_filter y after_filter ahora son protected por motivos de seguridad.

• Si has modificado el archivo views/index.phtml este fue ubicado en el directorio views/templates/default.phtml, es decir que le debes aplicar los cambios que quieras.

• Sustituye la función content() por View::content() y render_partial() por View::partial().

• Para inicializar tu aplicación se ha de utilizar el 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 en tus modelos utilizas el atributo $mode para establecer otros datos de conexión, debes reemplazarlo por $database, ver mas.
• Si Cargas librerias vía boot.ini ahora se usa libs= en vez de extensions= Y también se quita el prefijo kumbia.

KumbiaPHP 0.5

[modules]
extensions = kumbia.logger, kumbia.auth

KumbiaPHP 1.0

[modules]
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.

APP_PATH

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

Ejemplo:

 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 Componente Load para incluir dependencias.

CORE_PATH

Constante que contiene la ruta absoluta al directorio donde se encuentra el core de KumbiaPHP.

Ejemplo:

 echo CORE_PATH; //la salida es: /var/www/kumbiaphp/core/  

Para incluir archivos que se encuentre bajo este arbol de directorio es el mismo procedimiento que se explico para la constante APP_PATH

NOTA: El core de KumbiaPHP en la version 1.0 esta totalmente desacoplado del directorio de la aplicación. Ventajas de la Estructura de directorio

PUBLIC_PATH

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.

Ejemplo:

 //Genera un link que ira al controller: controller y action: action
 <a href="<?php echo PUBLIC_PATH ?>controller/action/" title="Mi Link">Mi Link</a> 

 //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
 <link rel="stylesheet" type="text/css" href="<?php echo PUBLIC_PATH ?>css/style.css"/> 

NOTA: siempre será mejor hacer uso de los helpers

Nueva Estructura de Directorios

En la versión de KumbiaPHP se incorpora la siguiente estructura de directorios, a continuación se detallan los elementos mas relevantes:

spirit/
|-- app
|   |-- application.php
|   |-- config
|   |-- controllers
|   |-- extensions
|   |   |-- filters
|   |   |-- helpers
|   |   `-- scaffolds
|   |-- index.php
|   |-- libs
|   |-- locale
|   |-- model_base.php
|   |-- models
|   |-- public
|   |-- temp
|   `-- views
|       |-- errors
|       |-- pages
|       |-- partials
|       `-- templates
|-- core
|   |-- console
|   |-- docs
|   |-- extensions
|   |   |-- helpers
|   |   `-- scaffolds
|   |-- kumbia
|   |-- libs
|   |-- tests
|   |-- vendors
|   `-- views
|       |-- errors
|       |-- partials
|       `-- templates

Anteriormente KumbiaPHP utilizaba un fichero index.php el cual servía para enrutar a cada aplicación utilizando inversión de control, esto erá poco flexible y resultaba en un consumo inadecuado de recursos, por lo tanto en esta nueva versión se preparó una nueva estructura de directorios donde cada aplicación posee un directorio independiente con su index.php (Front Controller) correspondiente el cual se encarga de cargar las librerías del framework.

Copiando el directorio app, tenemos toda la estructura para un nueva aplicación. Ya que podemos tener tantas aplicaciones como necesitemos con un único core.

Asimismo el núcleo, las extensiones de KumbiaPHP y otras herramientas que utilizarán las aplicaciones de manera global fueron agrupadas en el directorio core.

Ventajas de esta nueva estructura de directorios

• Mayor Velocidad :-)
• Cada aplicación tiene su propio front controller (index.php)
• Independencia total de nuestra aplicación respecto al core del framework.
• Cada aplicación tendrá sus propios directorios (public, temp, libraries, etc). En versiones anteriores si se tenia 40 aplicaciones significaba que todo iba al mismo public (css, img, js, etc).
• En cada actualización de KumbiaPHP, sólo se ha de pasar la carpeta de tu aplicación ("app") a la nueva versión de kumbiaPHP Framework y ya tendremos la última versión del Framework.

Explicando dir app

Este será el directorio sobre el cual trabajamos el 90% mientras desarrollamos nuestra aplicación. A continuación se explica en detalle cada uno de los directorios disponible para cada aplicación.

Directorio	Descripción
config	Archivos de configuración de nuestra aplicación (config.ini, routes.ini, databases.ini y boot.ini)
controllers	Estan agrupados los controladores (controllers) y/o módulos. Por defecto se encuentra el controller pages_controller.php
models	Estan agrupados los modelos (models).
views	Estan agrupados las vistas de los controladores (controllers). Por defecto se encuentran los directorios templates/, pages/, partials/ y errors/
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 KumbiaPHP
libs	En este directorio se pueden colocar clases propias con fines específicos o librerías externas al framework (vendors). Estas para ser utilizadas en los controladores (controllers) y/o Modelos (models).
temp	Este directorio contiene las carpetas y archivos creados cuando KumbiaPHP está cacheando un template, view o partial y cuando realiza operaciones de logs. Este directorio necesita permisos de escritura.
public	Agrupa las imágenes, css, javascript y files que serán utilizados por nuestra aplicación
locale	Agrupa los archivos para el soporte a la internacionalización i18n para la aplicación.
application.php	Super class de los controladores (ApplicationController).
model_base.php	Super class de los modelos (ActiveRecord).

application.php

Cada vez es mas usado en las aplicaciones creadas en PHP la Programación Orientada a Objetos (POO), KumbiaPHP Framework fomenta el uso de la misma, debemos hacer especial hincapié en el archivo application.php el cual fue concebido como una superclase (ApplicationController) padre de todos los controladores.

application.php

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.

En esta clase se encuentran dos métodos principales, dichos métodos se comportan como un filtro antes y después de ejecutar un controller.

El método initialize() se ejecuta antes de llamar al controller.

El método finalize() se ejecuta despúes de haber llamado al controller.

---

Ejemplo de application.php

application.php

model_base.php

De la misma manera como se relacionan los controladores con application.php, existe otra relación muy importante entre el model_base.php y los modelos. Todo lo que se define en model_base.php estará disponible en los modelos ya que es la class padre.

model_base.php es donde esta definida la super clase ActiveRecord.

 NOTA: Los modelos representan las tablas de nuestra Base de Datos.

application.php

Explicando dir core/

Directorio	Descripción
console	En este directorio se ubican los scripts de terminal que te ayudarán a construir y manejar algunos aspectos de nuestra aplicación
docs	En este directorio se encuentran los detalles de licencia y otros archivos inherentes a la documentación de KumbiaPHP
extensions	En este directorio se encuentran las extensiones compartidas por todas las aplicaciones
kumbia	En este directorio se ubica el núcleo de KumbiaPHP
libs	En este directorio se encuentran las librerias compartidas por todas las aplicaciones, las cuales el Equipo de Desarrollo se responsabiliza por su mantenimiento.
tests	En este directorio se ubican las pruebas unitarias para KumbiaPHP
vendors	En este directorio se ubican las librerias de terceros que son compartidas por todas las aplicaciones

config.ini

Se agregan opciones para un manejo mas apropiado de la configuración del framework, para la aplicación.

• metadata_lifetime Tiempo de vida de la metadata cacheada.
• database Base de datos a utilizar, especificada en databases.ini.
• production Indica si se encuentra en producción.
• cache_driver driver que se utilizara para el manejo de cache. KumbiaPHP cuenta con tres (3) driver: file, sqlite y memsqlite.
• locale Localización.
• routes Activar enrutamiento estatico.

;; Configuracion de Aplicacion

; Explicación de la Configuración:

; name: Es el nombre de la aplicación
; timezone: Es la zona horaria que usará el framework
; production: Indica si esta en producción
; database: base de datos a utilizar
; dbdate: Formato de Fecha por defecto de la Applicación
; debug: muestra los errores en pantalla (On|off)
; log_exceptions: muestra las excepciones en pantalla (On|off)
; charset: codificacion de caracteres
; cache_driver: driver para la cache (file, sqlite, memsqlite)
; metadata_lifetime: Tiempo de vida de la metadata cacheada
; locale: Localizacion
; routes: Activar enrutamiento estatico


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

[application]
name = "KUMBIA PROJECT"
;timezone = "America/New_York"
production = Off
database = development
dbdate = YYYY-MM-DD
debug = On
log_exceptions = On
charset = UTF-8
cache_driver = file
;metadata_lifetime = "+1 year"
;locale = es_ES
;routes = On

databases.ini

Este archivo viene a remplazar a environment.ini para establecer la configuración de conexión a la base de datos, en este sentido se eliminó el prefijo database, cada sección esta asociada a unos datos de conexión al motor de BD y a su vez esta corresponde al atributo database del archivo config.ini.

Veamos un ejemplo, si en el archivo de configuración config/config.ini tenemos database = development KumbiaPHP Framework tomara los datos de conexión que estén en la sección [development]

Lo mismo sucede para los modelos, el atributo $mode fue reemplazado por $database

class Usuarios extends ActiveRecord
{
    public $database = 'test';
}

Ahora KumbiaPHP Framework buscara los datos de conexión de la sección [test], para el modelo Usuarios.

; KumbiaPHP 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 = 192.168.1.103
username = sa
password = novosql
name = COMISION
type = mssql

[production]
host = 192.168.1.103
username = sa
password = novosql
name = COMISION
type = mssql

[test]
host = 192.168.1.103
username = sa
password = novosql
name = COMISION
type = mssql

boot.ini

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

Router

Mejoras de Rendimiento.

Dispatcher

Mejoras de Rendimiento.

Clase Kumbia

Mejoras de Rendimiento.

Vistas

Kumbia posee un sistema de presentación basado en Vistas (Views) que viene siendo el tercer componente del sistema 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 1.0(antigua 0.5.1) se incorporan dos(02) nuevos directorios en el directorio de vistas de nuestra aplicación los cuales son:

1. views/templates/
2. views/partials/

views/templates/

Los 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 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:

 
 class PruebaController extends ApplicationController 
 {
     public $template = 'plantilla';
 }

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

En la version 0.5 para determinar en que parte del template se debe renderizar se hacia uso de la función "content", ahora esa función se encapsuló en la clase View y se utiliza de la siguiente manera.

Este es mi template

<?php View::content() ?>

View::content() puede ubicarse en cualquier lugar del template.

views/partials/

Los partials (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 1.0(antigua 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 partials pueden representar cualquier tipo de 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

 <div style='background: #333eee; padding: 15px 10px 15px 10px; text-align: center'>
       <i><?php echo date('Y-m-d'); ?></i>
 </div>

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 laversió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.

 <?php View::partial('fecha') ?>

Describiendo la función de manera mas detallada:

  View::partial($partial, $time=false, $params=array())

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

  <?php View::partial('fecha', '+4 days') ?>

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

  <?php View::partial('fecha', false) ?>

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

  <?php View::partial('fecha', false, 'var: valor, var2: valor2') ?>

 <?php View::partial('fecha', false, array('var' => 'valor')) ?>

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:

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

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

 <?php 
   Load::models('usuario');
   $usuario = new Usuario();
   $result = $usuario->find(1);
 ?>

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 Load::model($modelo).

 <?php 
   $result = Load::model('usuario')->find(1);
 ?>

View::content()

Este método de la clase View viene a remplazar la función content(), esta se utiliza para indicar donde KumbiaPHP debe renderizar (mostrar) el contenido almacenado en el buffer de salida, es decir el próximo nivel de la vista.

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:

 <?php 
   class SaludoController extends ApplicationController
   {
       public function hola()
       {
           Flash::success('Hola mundo');
       }
   }
 ?>

Y en mi vista "hola.phtml"

   Saludo realizado:

   <?php View::content() ?>

View::helpers($helper)

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

Los helpers estan ubicados en miapp/extensions/helpers/, en ese directorio pueden existir tantos helpers como necesitemos KumbiaPHP, pero tambien pueden existir helpers en core/extensions/helpers/ en estos casos el framework da prioridad a los helpers ubicados en el directorio de la aplicación, esto quiere decir que si existen dos archivos con el mismo nombre en los directorios helpers antes descrito KumbiaPHP cargara el que se encuentra ubicado en el directorio de la aplicación (app).

Estos helpers pueden ser métodos con fines como formatear fechas, creación de tags HTML personalizados adecuados a las necesidades de nuestra aplicación, etc. veamos un ejemplo de un helpers.

//Ubicamos este código en un fichero de nombre: miapp/extensions/helpers/MiHelper.php

class MiHelper 
{
/**
 * Construye una lista desplegable para países
 **/
public static function paisSelect($id, $value=null) {
    //carga el modelo models/pais.php
    $Pais = Load::model('pais');

    $code = "<select name=\"$id\" id=\"$id\">";
    foreach($Pais->find() as $pais) {
        $code .= "<option value=\"$pais->id\"";
        if($pais->id == $value) {
            $code .= ' selected="selected"';
        }
        $nombre = htmlspecialchars($pais->nombre);
        $code .= ">$nombre</option>";
    }
    $code .= '</select>';

    echo $code;
}

Como vemos en el helper anterior se construye un tag select de acuerdo a ciertas necesidades y este representa una salida, es decir un view por eso se utilizan en las vistas (views) para hacer buen uso del MVC, la forma de utilizar el helper anterior en cualquier vista seria de la siguiente manera.

<?php
//Esta es una vista cualquiera

//la convención para cargar el helpers es pasar el parámetro tal como llamamos al fichero
//cargamos el helpers
View::helpers('MiHelper')

//Hacemos uso del helpers, con esto tendremos un select en el view
MiHelpers::paisSelect(1) 

?>

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

El método render($view, [$template]) se encuentra en la super clase ApplicationController es decir lo tenemos disponible solo en los controladores.

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 Template (el template es opcional) esto nos permite tener varias vistas (views) para la misma action incluso varios Template.

¿De que sirve esto?

Esto es una de las ventajas del manejo de vistas de 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.

Vamos a lo Práctico

Tenemos un controlador con una acción, pero deseamos que dicha acción tenga dos vistas asociadas y poderlas cambiar según sea el caso, el cambio de vista se dará de acuerdo a un parámetro que recibirá la acción del controlador.

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

<?php
class BlogController extends ApplicationController 
{
    public function saludo($var=null)
    {
        $this->usuario = 'Usuario';
    	if($var == 'adios'){
            //cambiamos el view
            $this->render('adios');
    	}
    }
}

Como se aprecia se cambiara el view de la acción si el parámetro es "adios" sino es pasado ningún parámetro KumbiaPHP seguirá la convención que buscara el directorio de views la vista asociada al nombre de la acción.

Ahora tenemos las vistas.

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

   <?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 Template veamos la misma acción pero ahora cambiara el template.

<?php
class BlogController extends ApplicationController 
{
    public function saludo($var=null)
    {
        $this->usuario = 'Usuario';
    	if($var == 'adios'){
            //cambiamos el view y el template
            $this->render('adios', 'otro_template');
    	}
    }
}

Ahora mostramos un nuevo Template llamado otro_template para cuando cambiamos el views a adios.

Ahora sin Template render($view, null)

Ahora indicamos que no deseamos mostrar el Template veamos la misma acción pero sin el template.

<?php
class BlogController extends ApplicationController 
{
    public function saludo($var=null)
    {
        $this->usuario = 'Usuario';
    	if($var == 'adios'){
            //cambiamos el view y sin template
            $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
class BlogController extends ApplicationController 
{
    public function saludo($var=null)
    {
        $this->usuario = 'Usuario';
    	if($var == 'adios'){
            //Mostrando un mensaje desde la acción
            Flash::notice('Adios '.$this->usuario);

            //sin el view y con el template por defecto
            $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.

<?php
class BlogController extends ApplicationController 
{
    public function saludo($var=null)
    {
        $this->usuario = 'Usuario';
    	if($var == 'adios'){
            //KumbiaPHP no mostrará nada
            $this->render(null, null);
            
            //enrutamos a otro controller
            return Router::route_to('controller: otro_controller');
    	}
    }
}

Logger

La clase Logger para el manejo de 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')?>

La salida de la instrucción anterior será lo siguiente:

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

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.

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

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)

Cache

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

Puedes obtener un driver de Cache utilizando el metodo driver que te proporciona la clase Cache.

Cache::driver($driver=null)

Este metodo permite obtener un manejador de cache específico, si no se indica, se obtiene el manejador de cache por defecto indicado en el config.ini.

Ejemplos:

// cache por defecto
$data = Cache::driver()->get('data');

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

// manejador para cache con APC
$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
string $group: grupo al cual pertenece el elemento cacheado (por defecto "default")

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

save($value, $lifetime=null, $id=false, $group='default')

Guarda los datos a cachear.

mixed $value: valor a cachear (automaticamente es serializado antes de guardar)
string $lifetime: tiempo de vida de los datos (formato de strtotime), si es null, los datos no expiran nunca.
string $id: identificador del elemento a almacenar, si no se especifica, se toma el id y grupo del ultimo get efectuado
string $group: grupo al cual pertenece

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

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

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.
string $id: identificador del elemento a almacenar, si no se especifica, se toma el id y grupo del ultimo get efectuado
string $group: grupo al cual pertenece

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

end()

Guarda los datos en la cache tomados del buffer de salida.

clean($group=false)

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

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

remove($id, $group='default')

Elimina un elemento específico de la cache

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().

cache($time, $type='view')

Para cachear una vista desde la acción:

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

Para cachear un template:

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

Si no desea cachear:

$this->cache(false);

ActiveRecord

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.

class Model extends ActiveRecord
{
    public function initialize()
    {
        //valida que la cedula sea unica
        $this->validates_uniqueness_of('cedula', 'message: La cedula ya existe');
    }
}

NOTA: El método initialize hace las veces de constructor y se ejecuta siempre por eso nuestros validadores deberían estar alli...

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

Valida que el campo sea único

string $field: campo a validar
array $params: array de parametros con nombre

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo (muestra un mensaje con el valor del campo)

Nota: Solo un parametro con nombre se muestra a la vez, teniendo prioridad el parametro con nombre message.

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

o

...
$this->validates_uniqueness_of('cedula', 'field: cedula')
$this->validates_uniqueness_of('cedula', array('field'=>'cedula'))
...

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

Valida que el campo sea tipo fecha

string $field: campo a validar
array $params: array de parametros con nombre

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

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

string $field: campo a validar
array $params: array de parametros con nombre

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

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

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
int $max: valor maximo
int $min: valor minimo
array $params: array de parametros con nombre

Parametros con nombre:
too_long: mensaje a mostrar cuando sea muy largo
too_short: mensaje a mostrar cuando sea muy corto
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())

Valida que el campo este incluido en los valores de la lista

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

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

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

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
array $list: lista de elementos
array $params: array de parametros con nombre

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

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

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

Valida que el campo coincida con el patron indicado

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

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

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

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

Valida que el campo sea numerico

string $field: campo a validar
array $params: array de parametros con nombre

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

...
$this->validates_numericality_of('cedula')
...

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

Valida que el campo sea un correo electronico

string $field: campo a validar
array $params: array de parametros con nombre

Parametros con nombre:
message: mensaje a mostrar
field: nombre del campo

...
$this->validates_email_in('email')
...

Modos de una Aplicación

KumbiaPHP ofrece dos modos de ejecución de una aplicación el cual es indicado en el config.ini, estos se describen a continuación:

Production

Indicando en el config.ini "production = On", se entra en el modo de producción, en este la cache de kumbiaphp framework 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 "production = Off", se entra en el modo de desarrollo, en este la cache de 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.

La para utilizar manualmente la cache de KumbiaPHP debes cargarla explicitamente indicándola en el boot.ini o utilizando el componente Load.

Load::lib('cache');

Cuando se cambia de modo, es necesario limpiar la cache que 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

En la versión 1.0(antigua 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".

Load::models($model)

Carga los modelos, se pueden cargar varios de manera simultánea indicándolos como argumentos múltiples del método o mediante un array. Asimismo se pueden cargar directorios completos de modelos.

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.

class UsuarioController extends ApplicationController 
{
  public function index()
  {
    //Se cargan los modelos Usuario y DatosPersonales
    //usuario.php y datos_personales.php
    Load::models('usuario', 'datos_personales');
  }
}

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

class UsuarioController extends ApplicationController {

  //Se cargan los modelos Usuario y DatosPersonales
  public $models = array('usuario', 'datos_personales');
  
  public function index()
  {}
}

Cargando un directorio de modelos

class UsuarioController extends ApplicationController {
  
  public function index()
  {
    /** se cargan los modelos en: 
     * mi_app/models/dir/* 
     * mi_app/models/dir2/model1.php
     * mi_app/models/model2.php
     */
    Load::models('dir', 'dir2/model1', 'model2')
  }

}

Load::model($model)

Obtiene una instancia del modelo indicado, esto permite hacer uso de modelos en cualquier lugar de la aplicación de manera intuitiva.

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

/**
 * Construye una lista desplegable para países
 **/
function pais_select($id, $value=null) {
    //carga el modelo models/pais.php
    $Pais = Load::model('pais');

    $code = "<select name=\"$id\" id=\"$id\">";
    foreach($Pais->find() as $pais) {
        $code .= "<option value=\"$pais->id\"";
        if($pais->id == $value) {
            $code .= ' selected="selected"';
        }
        $nombre = htmlspecialchars($pais->nombre);
        $code .= ">$nombre</option>";
    }
    $code .= '</select>';

    return $code;
}

Uso avanzado...

...
    //busca el país con ID 1
    Load::model('pais')->find(1);

    //carga el modelo ubicado en models/dir/user.php
    Load::model('dir/user')->find();

    //carga el modelo ubicado en models/user_group.php
    Load::model('user_group')->find();

...

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 Templates y Partials.

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

Ejemplos:

http://www.dominio.com/pages/show/organizacion/privacidad

enseñará la vista views/pages/organizacion/privacidad.phtml

http://www.dominio.com/pages/show/aviso

enseñara la vista views/pages/aviso.phtml

También se puede usar el routes.ini para llamarlo con otro nombre,

/aviso = pages/show/aviso

Asi al ir a www.dominio.com/aviso enseñara la vista views/pages/aviso.phtml

/organizacion/* = pages/show/organizacion/*

Al ir a www.dominio.com/organizacion/privacidad enseñará la vista en views/pages/organizacion/privacidad.phtml (si existe).

Ademas se pueden utilizar los Helpers y Partials dentro de estos views.

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

Mostrará un enlace que al hacer clic ira a dominio.com/pages/show/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

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

Ejemplo:

 
$value = Filter::get($s, 'htmlspecialchars', array('charset' => 'UTF-8'));

Asimismo se pueden aplicar filtros en cadena.

 
$value = Filter::get($s, 'trim', 'addslashes');

Los filtros en cadena no aceptan opciones de configuración, por lo tanto toman las opciones por defecto.

Filter::get_array($array, $options=array())

$array (array): un array de elementos a filtrar.
$options (array): array de configuración del filtro.

Los filtros se aplican a cada elemento del array.

Ejemplo:

 
$array = Filter::get_array(array('<b>Hola</b>', '<b>Adios</b>'), 'htmlspecialchars', array('charset' => 'UTF-8'));

 
$array = Filter::get_array(array('saludo' => '<b>Hola</b>'), 'htmlspecialchars', array('charset' => 'UTF-8'));

Filter::get_object($object, $options=array())

$object (object): objeto a filtrar.
$options (array): array de configuración del filtro.

Los filtros se aplican a cada atributo del objeto.

Ejemplo:

$object = Filter::get_object($usuario, 'htmlspecialchars', array('charset' => 'UTF-8'));

Filtros

Los filtros que existen actualmente son los siguientes:

addslashes

Escapa las comillas dobles y simples en una cadena de texto.

$value = Filter::get('hola "gente"', 'addslashes');

alnum

Filtra la cadena eliminando los caracteres que no son alfanumericos o espacios.

$value = Filter::get('hola "gente112"', 'alnum');

alpha

Filtra la cadena eliminando los caracteres que no son alfabéticos o espacios.

$value = Filter::get('hola "gente112"', 'alpha');

date

Verifica que sea una fecha valida en el formato YYYY-MM-DD.

if(Filter::get($s, 'date')) {
    ...
}

digits

Filtra la cadena eliminando los caracteres que no son digitos.

$value = Filter::get('hola "gente112"', 'digits');

htmlentities

Escapa los elementos del lenguaje html con sus correspondientes entidades.

$value = Filter::get('<p>"hola"</p>', 'htmlentities');

Opciones:
charset: codificación de caracteres de la cadena a escapar.

htmlspecialchars

Escapa caracteres especial de html.

$value = Filter::get('<p>"hola"</p>', 'htmlspecialchars');

Opciones:
charset: codificación de caracteres de la cadena a escapar.

int

Convierte un valor a tipo entero.

$value = Filter::get('1.2', 'int');

ipv4

Verifica si la cadena tiene el formato ipv4.

if(Filter::get($s, 'ipv4')) {
    ...
}

lower

Convierte una cadena de texto a minusculas.

$value = Filter::get('TEXTO', 'lower');

md5

Calcula el hash md5 para el valor indicado.

$value = Filter::get('TEXTO', 'md5', array('binary' => true));

Opciones:
binary: indica si se usa modo binario

nl2br

Convierte el caracter de nueva linea a "<br>".

$value = Filter::get('TEXTO\nTexto2', 'nl2br');

numeric

Filtra una cadena solo permitiendo valores numericos.

$value = Filter::get('a1.2', 'numeric');

stripslashes

Filtra una cadena haciendo la operación inversa a addslashes.

$value = Filter::get('\"Hola\"', 'stripslashes');

stripspace

Elimina los espacios.

$value = Filter::get('  Hola  ', 'stripspace');

striptags

Elimina las etiquetas HTML.

$value = Filter::get('<p>Hola</p>', 'striptags');

trim

Elimina los espacios en blanco a la izquiera y a la derecha.

$value = Filter::get('   Hola   ', 'trim');

upper

Convierte la cadena a mayúsculas.

$value = Filter::get('hola', 'upper');

Extendiendo el componente Filter

El componente Filter puede extenderse permitiendo al usuario crear sus propios filtros, para este fin el usuario debe hacer uso de la interface "FilterInterface", la cual se describe a continuación:

interface FilterInterface
{
    /**
     * Metodo para ejecutar el filtro
     *
     * @param string $s cadena a filtrar
     * @param array $options opciones para el filtro
     **/
    public static function execute ($s, $options);
}

Los filtros de usuario deben ubicarse en el directorio "app/extensions/filters/".

Por convenio la clase que corresponde al filtro debe llevar el sufijo "Filter" y el archivo debe llamarse igual que la clase pero en notación smallcase.

Ejemplo: Un filtro que permite obtener la extension de un archivo, pasandole como valor el nombre del archivo.

app/extensions/filters/file_extension_filter.php

/**
 * Filtro para obtener la extensión de un archivo
 **/
class FileExtensionFilter implements FilterInterface
{
   public static function execute($s, $options=array()) 
   {
       return strchr($s,".");
   }
}

Y se utilizaría de la siguiente manera:

$ext = Filter::get('/home/yo/prueba.php', 'file_extension');

Filtrando datos enviados en el Request

El controller dispone de ciertas facilidades, en sus métodos: post, get y request, se puede indicar diversos filtros para aplicar al valor recibido.

Ejemplo:

class UsuarioController extends ApplicationController
{
    public function save()
    {
        if($this->has_post('usuario')) {
            $usuario = new Usuario($this->post('usuario', 'trim'));
            $usuario->save();
        }
    }
}

En el ejemplo anterior, los datos enviados en el array de campos "usuario", son filtrados con un trim, cargados por el constructor del objecto ActiveRecord y posteriormente se guarda en la base de datos.

Carga Selectiva, Inyección de Dependencias y el Componente Load

El componente Load, esta diseñado especialmente para satisfacer las necesidades de Carga Selectiva e Inyección de Dependencias, con este componente disponemos de los elementos de KumbiaPHP Framework (vendors, libraries y models) donde así lo necesite nuestra aplicación.

Load::lib($lib)

El método library del componente Load nos permite cargar dinámicamente aquellas clases que tengamos definidas en el dir app/libs/ a fin de utilizarlas en los controladores(controllers) y/o Modelos(models).

class UsuarioController extends ApplicationController 
{
  public function index()
  {
    //Se carga la librería app/libs/my_util.php
    Load::lib('my_util');
  }
}

NOTA: Por convención del método Load::lib($lib) busca primero en el directorio app/libs/ y en caso de no encontrar la biblioteca requerida pasaría a buscar en el directorio core/libs/, por lo que podríamos cargar dinámicamente la librería Auth del core de la siguiente forma

class UsuarioController extends ApplicationController 
{
  public function index()
  {
    //Se carga core/libs/auth/auth.php, siempre que no exista algún archivo
    //con el mismo nombre en app/libs/ ya que KumbiaPHP da prioridad a tu app sobre el core.
    Load::lib('auth');
  }
}

Persistencia de Datos en el Controller

En ocasiones se necesita la persistencia de algunas variables en la ejecución de nuestros controladores, lo mas común en estos casos es guardar consultas avanzadas o bien pudiera los articulos de carro de compras. Para estos casos y mas que se puedan presentar KumbiaPHP hace persistente las variables para el controlador dependiendo el caso.

Para suplir esta necesidad se incoporan los siguientes métodos.

...
//hace persistente la variable $data
$this->set_persistent('data', 'valor');
...

...
//recupera la persistencia de la variable $data
$this->get_persistent('data');
...

...
//destruye la persistencia de la variable $data
$this->destroy_persistent('data');
...

Session

En la extensions Session se quitan dos métodos que estaban descontinuado (deprecated) los cuales son:

• set_data()
• get_data()

Quedando la extensions Session con los siguientes métodos para el manejo de la sessiones.

set($index, $value, $namespace='default')

Crear o especifica el valor para un indice de la sesión actual.

Session::set('usuario', 'Administrador');

get($index, $namespace='default')

Obtener el valor para un indice de la sesión actual.

Session::get('usuario');//retorna 'Administrador'

unset_data($index, $namespace='default')

Elimina el valor para un indice de la sesión actual.

Session::unset_data('usuario');

has($index, $namespace='default')

Verifica que este definido el indice en la sesión actual.

Session::has('id_usuario');//retorna false.

NOTA: $namespace es un espacio individual en el cual se pueden contener las variables de sesión, permitiendo evitar colisiones con nombres de variables.

Upload

Anteriormente en los controladores, estaban disponibles los métodos upload_file y upload_image, ya que realmente el controlador no depende de estos para su correcto funcionamiento, estos fueron agrupados en el componente Upload. Este componente permite subir tanto archivos e imagenes al servidor donde se aloja tu aplicación.

Upload::file_in_path($name, $path, $new_name=null)

Sube un archivo la ruta indicada.

$name (string): nombre del archivo en el formulario (se revisa en $_FILES)

$path (string): ruta donde se subira. Ejemplo: "/var/www/public/app/temp/files/"

$new_name (string): indica el nuevo nombre para el archivo, por defecto se toma el nombre original.

...
Upload::file_in_path('archivo', APP_PATH . 'temp/mis_archivos/');
...

Upload::file($name, $new_name=null)

Sube un archivo al directorio público "files/upload".

$name (string): nombre del archivo en el formulario

$new_name (string): indica el nuevo nombre para el archivo

...
Upload::file('archivo');
...

Upload::image($name, $new_name=null)

Sube una imagen al directorio público "img/upload".

$name (string): nombre del archivo en el formulario

$new_name (string): indica el nuevo nombre para el archivo

...
Upload::image('archivo');
...

Partials de Paginación

Como complemento para el paginador de ActiveRecord, através de vistas parciales se implementan los tipos de vistas de paginación más comunes, estos se ubican en el directorio "core/views/partials/paginators" y estas en capacidad de personalizarlos en tu aplicación aprovechando las características de renderizado de vistas parciales.

Classic

Resultado Final

Vista de paginación clásica.

Parametros de configuración:

page: objeto obtenido al invocar al paginador.

show: número de paginas que se mostraran en el paginador, por defecto 10.

url: url para la accion que efectua la paginacion, por defecto "module/controller/page/" y se envia por parametro el numero de pagina.

View::partial('paginators/classic', false, array('page' => $page, 'show' => 8, 'url' => 'usuario/lista'))

Digg

Vista de paginación estilo digg.

Parametros de configuración:

page: objeto obtenido al invocar al paginador.

show: número de paginas que se mostraran en el paginador, por defecto 10.

url: url para la accion que efectua la paginacion, por defecto "module/controller/page/" y se envia por parametro el numero de pagina.

View::partial('paginators/digg', false, array('page' => $page, 'show' => 8, 'url' => 'usuario/lista'))

Extended

Resultado Final

Vista de paginación extendida.

Parametros de configuración:

page: objeto obtenido al invocar al paginador.

url: url para la accion que efectua la paginacion, por defecto "module/controller/page/" y se envia por parametro el numero de pagina.

View::partial('paginators/extended', false, array('page' => $page, 'url' => 'usuario/lista'))

Punbb

Vista de paginación estilo punbb.

Parametros de configuración:

page: objeto obtenido al invocar al paginador.

show: número de paginas que se mostraran en el paginador, por defecto 10.

url: url para la accion que efectua la paginacion, por defecto "module/controller/page/" y se envia por parametro el numero de pagina.

View::partial('paginators/punbb', false, array('page' => $page, 'show' => 8, 'url' => 'usuario/lista'))

Simple

Resultado Final

Vista de paginación simple.

Parametros de configuración:

page: objeto obtenido al invocar al paginador.

url: url para la accion que efectua la paginacion, por defecto "module/controller/page/" y se envia por parametro el numero de pagina.

View::partial('paginators/simple', false, array('page' => $page, 'url' => 'usuario/lista'))

Ejemplo de uso

Supongamos que queremos paginar una lista de usuarios.

Para el modelo Usuario en models/usuario.php:

<?php
class Usuario extends ActiveRecord
{
    /**
     * Muestra los usuarios de cinco en cinco utilizando paginador
     *
     * @param int $page
     * @return object
     **/
    public function ver($page=1)
    {
        return $this->paginate("page: $page", 'per_page: 5');
    } 
}
?>

Para el controlador UsuarioController en controllers/usuario_controller.php:

<?php
class UsuarioController extends ApplicationController
{
    public $models = array('usuario');

    /**
     * Accion de paginacion
     *
     * @param int $page
     **/
    public function page($page=1)
    {
        $this->page = $this->Usuario->ver($page);
    } 
}
?>

Y en la vista views/usuario/page.phtml

<table>
 <tr>
  <th>Id</th>
  <th>Nombre</th>
 </tr>
 <?php foreach($page->items as $p): ?>
 <tr>
  <td><?php echo $p->id; ?></td>
  <td><?php echo $p->nombre; ?></td>
 </tr>
 <?php endforeach; ?>
</table>

<?php View::partial('paginators/classic', false, array('page' => $page)); ?>