DRY, pero no tan DRY

A la metodología de programación que busca no repetir innecesariamente código se la conoce como DRY (Don't Repeaty Yourself, No Te Repitas).

Hace unos posts escribía sobre una técnica que consistía en escribir algunas acciones básicas en el AppController, a modo de scaffolding, de modo que no necesitase escribir otra vez ese código en los nuevos controladores que iba creando.

A este post me respondía AD7six, del que había tomado la idea en un post suyo antiguo. En su comentario me hacía ver que, a la larga, me iba a encontrar con problemas a medida que los controladores empezasen a tener excepciones y que acabaría reescribiendo todo.

Por supuesto, AD7six tiene toda la razón al indicar esto, aunque yo creo que la técnica puede seguir siendo válida para  partes de las aplicaciones que sólo necesiten acciones CRUD muy básicas (como mantenimiento de listas de opciones, categorías, etc). En realidad, también se podría usar el scaffolding.

¿Qué solución tenemos a esta situación en la que el código es repetitivo y sin embargo no debería dejarse en un método genérico?

Pues la respuesta es Bake, la utilidad de líneas de comandos para generar Modelos, Controladores y Vistas en CakePHP.

¿Y si no te gusta el código que genera? Pues a aprender a crear tus propias task para montar controladores, y modelos. Y plantillas para las vistas.

De este modo, podemos combinar lo mejor de ambos mundos: no tener que escribir 20 veces el mismo código (lo hace bake) y poder adaptarlo según sea necesario.

Sobrecargando el campo upload

Repasemos un momento.

En PHP, cuando tienes uno o varios campos tipo "file" para subir archivos en un formulario y éste es enviado al pulsarse un botón Submit, PHP coloca los datos de los archivos subidos en el array $FILES. No tenemos más que ir a buscar allí los datos, hacer las comprobaciones necesarias y usar move_uploaded_file() para poner los archivos en los lugares adecuados.

CakePHP va un paso más allá y coloca esos datos en los campos adecuados del array de datos que viene del formulario, lo que hace aún más fácil usarlos. En concreto, el array asociativo que nos da la información de cada archivo tiene estas claves:

tmp_name
name
type
size
error

Y ahora, el truco:

Supongamos que tenemos un Modelo con un campo file con el que vamos a subir un archivo. Por tanto, en la vista en la que construimos el formulario ponemos algo así como:

echo $form->input('Modelo.file', array('type' => 'file'));

Resulta que si ponemos un campo del estilo de:

echo $form->input('Modelo.file.extra');

Cuando hagamos el proceso del archivo subido nos vamos a encontrar más claves en el array de información, exactamente tantas como campos Modelo.file.* hayamos creado:

extra

tmp_name

name

type

size

error

¿Útil? Puede que sí. Gracias a este pequeño truco he podido crear un formulario en el que el usuario puede marcar que sea borrado un archivo ya existente, si no quiere subir otro para que lo sustituya.

Unit-testing y yo

Hace unos pocos posts comenté que una de las estrategias que estaba adopotando en mi desarrollo, junto a la modularización por plugins, es el unit-test y el desarrollo dirigido por tests.

Como programador autodidacta uno de los grandes problemas que encuentro es aprender de una forma sistemática y fundamentada. Uno no dispone de la estructuración que una formación más reglada te puede proporcionar. De este modo, temas como los patrones de programación o el uso de los test en el proceso de desarrollo no te resultan evidentes al principio, a veces, ni siquiera comprensibles.

Bueno, que me enrollo. Yo quería hablar de cómo llegué al punto en el que efectivamente uso los tests para probar mi software y cada vez más sigo una metodología dirigida por ellos. Pero quizá convenga empezar por explicar que es eso de los tests.

Test: probando el software

Al principio uno escribe trozos de código y ejecuta el programa para ver qué pasa. Es una manera básica de probar un software. De hecho, eso es básicamente un test de software: ejecutarlo y ver si ofrece los resultados esperados.

Cuando empecé con CakePHP, gracias a que proporciona una base completa para una aplicación, hacía más o menos eso mismo.

Estos tests "a ojímetro" no funcionan tan mal en situaciones sencillas, pero en cuanto las cosas empiezan a complicarse se vuelven ineficientes en progresión geométrica. En un momento dado resultan inútiles.

Cuando aparece un error en la aplicación, puede que haya fallado dentro de una función o método, pero es muy posible que la causa del error esté muy lejos en la pila de llamadas. Es decir, que el error real esté en un lugar y con la información disponible no tengamos forma de encontrarlo sin revisar toda la aplicación.

Eso sin mencionar la dificultad, por ejemplo, de probar los múltiples escenarios en que una aplicación puede funcionar. ¿De qué manera puedes saber que has probado el efecto de introducir ciertos datos de diferentes maneras? ¿Alguno de ellos puede generar un error?

Y, finalmente, si realizas un cambio de código, ¿cómo vuelves a probar todo otra vez para asegurarte de que el cambio no tiene efectos indeseados en otra parte?

Se hace necesario utilizar una metodología más sistemática y eficaz, que permita replicar las pruebas las veces que haga falta en multiplicidad de condiciones. Aquí es donde entra el Unit-testing.

Unit-rest: prueba de unidades de software

Como dice el título del apartado, el unit-test es una metodología de prueba de software que se basa en la prueba aislada de las unidades mínimas en que podemos dividir nuestro código. En el caso de CakePHP, que es un framework orientado a objetos, esas unidades son los métodos de las diferentes clases que componen la aplicación.

Por otro lado, los test serían programas que se encargan de llamar a las distintas unidades con diferentes condiciones (parámetros que se pasan, constantes globales, etc.) y comparar el resultado que ofrecen con los resultados que esperamos. Por ejemplo, si una función calcula el doble de un número, el test consistiría en algo así como:

$resultado = dobleDe(100);
    $esperado = 200;
if($resultado == $esperado) {
    echo 'OK';
} else {
    echo 'algo falla en dobleDe';
}

Al ser un programa podemos repetirlo cuantas veces queramos, en especial si hacemos algún cambio en la función dobleDe(), lo que nos diría si nuesto cambio o refactor está afectando al funcionamiento del código.

También podríamos probar multitud de valores para asegurarnos de que la función devuelve los valores correctos, sobre todo en ciertos puntos críticos. Por ejemplo, una función para calcular el precio con descuento por volumen en una tienda podría tener los intervalos:

Unidades                  descuento
menos de 10 ud.       0 %
entre 10 y 20 ud       3% de descuento
más de 20 ud            5% de descuento

Aquí tendríamos que probar al menos los siguientes valores de unidades:

<10 =10 >20 y <20 =20 >20

Es decir, tendríamos que escribir al menos 5 test variando las unidades de producto para ver si la función nos devuelve el precio correcto para una combinación de producto y cantidades.

Ayudas al Unit-Test

Por supuesto, escribir los tests "a pelo" es un trabajo considerable. Para ayudar en la tarea existen bibliotecas como SimpleTest, en la cual se basa el Test Suite de CakePHP.

En conjunto la Test Suite nos proporciona un entorno para probar las clases que escribimos para nuestra aplicación, garantizándonos el mínimo de funcionalidad que necesitamos para que nuestros modelos, controladores y vistas puedan ser probados, así como funciones específicas para hacer los tests.

Un concepto básico son las aserciones o asserts. Se trata de afirmaciones que hacemos sobre el resultado de una unidad. Por ejemplo, que el resultado va a ser igual a cierto valor, que será cierto o falso, o que se coincidirá con una determinada expresión regular.

CakePHP tiene una clase CakeTestCase que incorpora la mayoría de asserts que podemos necesitar, así, podremos escribir un test como el siguiente:

$result = $this->Post->find('count');
$this->assertEqual($result, 5):

Que básicamente quiere decir que el find('count') debería encontrar 5 registros en la base de datos que estamos usando de prueba.

Otra ayuda importante son los Mock Objects. Estos objetos nos permiten imitar el comportamiento de objetos de nuestra aplicación, pero sin que ejecuten su código real, sino que ofrecen la misma intefaz y podemos programarlos para que devuelvan ciertos resultados que nos interesen.

Es decir, que si el método que estamos probando llama a un objeto "mockeado", no se ejecutará el código del objeto original, sino que el "mock" nos devolverá el valor que le hemos configurado que devuelva.

Eso nos permite aislar el código que estamos probando del resto de la aplicación, lo que hace más fiable el test (ejecuta sólo el código que probamos) y nos permite jugar con diferentes escenarios.

Un ejemplo típico es hacer un Mock del EmailComponent. Puede que en nuestra máquina de test no podamos enviar correo usando el EmailComponent, pero haciendo un Mock podemos simular que lo ha enviado y basarnos en eso para probar una parte de la aplicación. O también podemos probar la condición de que no funciona y ver cómo la supera nuestra aplicación.

También es posible probar condiciones de error. Es posible utilizar la función expectError para detectar que nuestro código produce un error. Por ejemplo, cuando lanzas un error desde el código si los datos que llegan a un método son inválidos.

La asserts, además, permiten a la Test Suite realizar algunas estadísticas con tus test. De este modo, puedes tener un número de tests sobre una clase y saber cuántos pasan, cuántos fallan y si se han provocado excepciones.

Desarrollo dirigido por tests

El desarrollo dirigido por tests es una metodología en que usas el Unit-testing como base para desarrollar tus aplicaciones. Se trata de escribir los tests antes que el código de las unidades.

¿Cómo?

Sí, al principio me costó mucho entender esta idea, que ahora me parece de lo más evidente.

En el fondo, escribir un test para una unidad de software es definir de una manera formal sus especificaciones e interfaz: qué parámetros debe recibir y qué resultados ha de proporcionar y en qué formato.

Esto puede hacerse antes de escribir el código, por supuesto. Tú sabes lo que quieres que haga un método antes de escribirlo. En realidad, en un equipo de desarrollo, ni siquiera tendría que ser la misma persona la que prepara los test y la que realiza el código.

Preparar el test te hace pensar muy a fondo en la interfaz del método. Y escribir código para cumplir el test te obliga a estar muy enfocado en lo que estás haciendo. Y, sobre todo, te proporciona una red de seguridad para el futuro.

Tests y refactor

En un momento dado te plantearás refactorizar el código. Los tests te ayudan a garantizar que no se rompe nada. Es genial, en serio: incorporas unas modificaciones y pruebas, si falla, revisas de nuevo y reescribes, vuelves a probar, y así sucesivamente hasta que vuelves a pasar el test. Y, si no, puedes volver a la revisión anterior que sí funcionaba.

Si se trata de añadir funcionalidades nuevas, los test también te ayudan. Por un lado, los tests originales te garantizan que el nuevo código no rompe la funcionalidad original. Por otro lado, debes añadir tests que prueben las nuevas características.

Unit-test y calidad de vida

Pues mejora mucho. Me costó llegar a realizar tests para las diferentes clases. Tiene su complicación probar un controlador por ejemplo, o un behavior. Sin embargo, superadas esas dificultades (lo que a su vez me permitió aprender mucho acerca de cómo funciona CakePHP), el resultado no puede ser mejor.

Mi código está mejor escrito y más pensado. Mi trabajo es más focalizado en objetivos concretos. Además, debido a que con frecuencia tengo que interrumpir el desarrollo para dedicarme a otras actividades, me resulta mucho más fácil retomar el trabajo después de un tiempo. También me permite, por ejemplo, dedicar ratos sueltos a resolver pequeños problemas y avanzar en los proyectos, tomando algún problema detectado o algún test fallido y viendo cómo resolverlo.

Al poder trabajar con partes aisladas, no tienes miedo a romper la aplicación y tener muchos frentes abiertos. Te centras en una tarea y la resuelves, luego otra y luego otra.

La inversión de tiempo en aprender a usar los test y en crearlos realmente merece la pena.

Saber si haces buenos tests

El Test Suite incluye soporte para analizar la cobertura de código de tus test mediante Xdebug. Me costó un poco preparar mi sistema para poder utilizarlo y ha sido una especie de revelación cuando lo conseguí. Además, Xdebug mejora la información que te devuelve la aplicación cuando hay errores de PHP, mostrándote la pila de llamadas y diversa información.

La cobertura de código te indica qué porcentaje del código probado es ejecutado en realidad. Te ayuda a descubrir partes del código que no se ejecutan, condiciones que no has probado y otros muchos detalles, pues te muestra los fragmentos no ejecutados.

Al disponer de esta información es más fácil hacer tests para todo tipo de condiciones, o saber si tienes que crear nuevos tests aunque cubras el 100% del código con los que tienes, al añadir nuevas funcionalidades o hacer refactor de un método.

Los límites de los test

Los test no son la solución para garantizar un programa perfectamente libre de errores. Los test te informan de que una unidad de software hace lo que esperas que haga, suponiendo que has cubierto todos los escenarios posibles con los tests.

Sin embargo, la tranquilidad y seguridad que te proporcionan, la focalización que te aportan y la objetividad y claridad que te dan a la hora de definir tus tareas de programación, tienen un valor que compensan claramente estos límites.

Obtener el nombre de un modelo a partir del array de datos

Actualizado:

José Lorenzo recomienda una forma más compacta en los comentarios:

$modelName = key($model)

No había caído en la función key, que extrae la clave del elemento actual del array, si no hemos hecho nada con él que haya podido variar su puntero interno, el elemento será el primero y el resultado será el mismo que con el otro método.

El método alternativo

Dejo aquí el post y el método original. La diferencia es que éste siempre devolverá la primera clave, con independencia de dónde esté el puntero del array.

Esta semana estoy trabajando en un sistema de autorización basado en reglas que me está trayendo de cabeza. Mientras tanto, este pequeño snippet me está resultando muy útil, he debido leerlo en algún sitio porque a mí solo no se puede ocurrir, pero no recuerdo dónde:

$modelName = array_shift(array_keys($model));

Extrae la clave del array de modelo, si tienes un array de datos de un modelo sin que tengas referencia a la clase ni forma de obtnerla. Algo del tipo:

$model = array('Modelo' => array('id' => 12312, 'name' => 'fede'));

El código extraerá correctamente 'Modelo' en $modelName, y ya lo puedes utilizar para lo que quieras.

Plantillas para generar vistas con Bake

Una de las estrategias que puede ayudar más en agilizar el desarrollo con CakePHP es hacer un uso intensivo del shell Bake.

A poco que conozcas Cake habrás oído hablar de esta utilidad capaz de generar modelos, controladores y vistas, prefabricados, proporcionándote así una buena base para trabajar, tanto que a veces no necesitas mucho más para disponer de un "backend" suficiente.

Sin embargo, es posible que no te guste de todo el código generado, o que no se adapte completamente a lo que necesitas o a los requisitos del proyecto. ¿No sería estupendo poder personalizar ese código?

En este post voy a intentar explicar las bases de cómo crear plantillas para las vistas generadas con Bake.

Las plantillas

Es una buena idea echar un vistazo a las que vienen de serie, que se encuentran en la carpeta cake/console/libs/templates/views. Parece un galimatías, ¿verdad? Bueno, no es tan complicado una vez que comprendes como va.

Para comenzar a modificar estas plantillas lo mejor es que las copies a la carpeta de la aplicación. Las debes poner en app/vendors/shells/templates/views.

Hay cuatro plantillas:

form.ctp: para generar las vistas add.ctp, admin_add.ctp, edit.ctp y admin_edit.ctp.

home.ctp: para generar la vista home.ctp

index.ctp: para generar las vistas index.ctp y admin_index.ctp

view.ctp: para generar las vistas view.ctp y admin_view.ctp

¿Cómo se escriben estas plantillas?

El HTML se escribe directamente, como si fuese una vista normal.

Puedes usar código CakePHP para generar partes de la vista. Dispones de varias variables que hacen referencia al modelo y los datos que el controlador pasará a la vista. Se asumen varias convenciones que intentaré esplicar:

$action: contiene la acción que será llamada (ejemplo "add"). Puedes chequearla para incluir o no elementos según sea una acción de crear o editar el registro.

$fields: contiene un array con los campos del modelo.

$associations: un array que contiene las asociaciones del modelo, con las cuatro claves (hasAndBelongsToMany, belongsTo, hasMany y hasOne).

$singularHumanName y $plurarHumanName: el nombre del modelo en formato legible por humanos.

$modelClass: la clase del modelo

$displayField: el campo que esté definido como tal en el modelo, o el que Cake toma por defecto (normalmente title).

$pluralVar: el nombre del modelo en plural en formato de variable. Se asume que una acción index pasas los resultados del find o del paginate a la vista en una variable con el nombre del modelo en plural. Por ejemplo, si el modelo es Post, la variable en la vista sería $posts.

$schema: nada menos que el schema o definición de la tabla en la base de datos.

El código PHP que quieras que tenga la vista se tiene que escribir indirectamente a través de PHP, habitualmente usando algo así como:

<div id="view_title">
   <h1><?php echo "<?php __('Admin $pluralHumanName'); ?>" ?></h1>
   <p><?php echo "<?php __('Manage $pluralHumanName records'); ?>" ?></p>
</div>

Fíjate que los prefijos $ de las variables "reales" deben ser escapados con \ para evitar un error de variable inexistente en la generación. Aparte de eso, puedes usar las variables de la plantilla a tu gusto.

En fin, quizá sea mejor que veas algunos ejemplos. En particular, las vistas edit e index, que son las que yo he modificado.

¿Personalizar modelos y controladores?

No he entrado en este tema, pero básicamente consiste en modificar las tasks que los generan, trabajo que parece más tedioso que difícil. Echa un vistazo en cake/console/libs/tasks/. Puedes copiar las tasks en app/vendors/shells/tasks para modificarlas.

El código es bastante claro, por lo que no parece difícil adaptarlo a tus preferencias concretas.

Volver a la página correcta (y a la ordenación, también)

Este es un tema recurrente. La situación típica es la siguiente:

Nos encontramos en la típica vista index que muestra un listado paginado de registros (posts, usuarios, lo que sea). Supongamos que estamos en la página 17 de 25, con los registros ordenados por algún criterio y que pulsamos el enlace para ver o editar alguno.

Al volver de la edición, nos llevamos el gran palo: otra vez en la primera página y ordenados por id.

¿Cómo hacemos para volver a la misma página y a ser posible a las mismas condiciones de ordenación?

Hay varias técnicas, la última que estoy probando la encontré en este enlace. La explico:

Para obtener la URL a la que queremos redirigir recurriremos al método referer() del controlador, que nos devuelve la URL de la que venimos. Este método nos conserva los parámetros del URL relacionados con la paginación.

Si estábamos en /app/posts/index/page:17 y consultamos referer() en admin_edit(), por ejemplo, nos devolverá ese valor.

Sin embargo, recuerda que las acciones como admin_edit son llamadas dos veces consecutivas. La primera es explícita, cuando hacemos clic en el enlace que nos lleva a ella. En esa situación, referer() nos devolverá la URL de la acción de procedencia. Por tanto, esa es la URL que deberíamos usar para redirigir después de guardar los cambios.

Pero la segunda vez es implícita, cuando pulsamos el botón de envío del formulario, volvemos a admin_edit, con lo cual referer() tendrá la propia URL de la acción. Es en esta pasada cuando se realiza habitualmente la redirección a la acción de index.

Dicho de otro modo: la primera vez que llegamos a la acción editora tenemos que obtener referer() y guardarlo de algún modo para recuperarlo en la segunda pasada.

Una forma es pasar el valor de referer() a la vista en la primera pasada.

$this->set('returnTo', $this->referer());

Así podremos recuperarlo para varios usos:

* Para crear enlaces de cancelación o regreso.

link(__('Return to Admin Index', true), $returnTo);?>

* Para añadir un campo oculto al formulario en el que anotar ese valor y poder retomarlo en la segunda pasada.

input('App.returnTo', array('type' => 'hidden', 'value' => $returnTo)); ?>

Esta última opción, nos permite recuperar la URL correcta, con todos los parámetros de paginación que tuviese, y redirigir la acción correctamente. El valor estará en el array $this->data, bajo las claves con las que hayas puesto el nombre del campo en el formulario.

if (isset($this->data['App']['returnTo'])) {
   $this->redirect($this->data['App']['returnTo']);
}

Otro caso

Otra situación es la que ocurre en acciones que redirigen al index sin mostrar ninguna vista, como podría ser un enlace para borrar registros.

En ese caso, podemos redirigir al referer().

$this->redirect($this->referer()

Siempre puede ser conveniente tener un plan B, es decir, en caso de que referer() nos devuelva un valor no válido, tratar de redirigir a la acción básica, aunque perdamos la información de paginado.

Múltiples botones submit en un formulario

Necesitaba conseguir lo que dice el título, o sea, disponer de varios botones de submit en un formulario, de modo que, además del envío normal del formulario, pudiese detectar qué botón concreto se ha pulsado para realizar ciertas operaciones en función del mismo.

Lo que no sabía era cómo hacerlo "a la Cake".

Bueno, pues es sencillo:

1. En el formulario, añade un control $form->submit con opciones para indicarle un nombre y un valor que luego podrás capturar en el controller. Por ejemplo:

$form->submit(__('Reset Filter', true), array('value' => true, 'name' => 'resetFilter'))

Ahora, para comprobar si el botón ha sido pulsado, no tienes más que mirar en la propiedad params del controlador, de esta manera:

$this->params['form']['resetFilter']

Que contendrá el valor del botón que hayas pulsado. Es decir, puedes tener varios botones con el mismo "name" y distinto valor, o bien simplemente botones con distintos "name" y chequear si dentro de $this->params['form'] existen las claves correspondientes.