Creando un wiki con Symfony en menos de 20 minutos

Este tutorial es una traducción autorizada del original Application Lego: Build a Wiki with Symfony in 20 Minutes, escrito por François Zaninotto y publicado el 5 de abril de 2008 en su blog Redo The Web. François es el principal autor y responsable de la documentación oficial de Symfony, co-autor del libro oficial, creador de numerosos plugins y colaborador en el desarrollo del núcleo de Symfony. Actualmente, François trabaja como director tecnológico de una empresa francesa de reciente creación.

En este tutorial se muestra lo rápido que se puede llegar a programar con Symfony. Además, se muestran algunas de las posibilidades más interesantes del generador de administraciones de Symfony y se utilizan algunos plugins muy útiles.

Instalación

Si no has instalado Symfony previamente, la forma más rápida de comenzar es descargar el archivo del sandbox de Symfony, que contiene todas las librerías necesarias y un proyecto vacío ya creado. Una vez descargado, tienes que descomprimirlo en la raíz de tu servidor web, de forma que puedas acceder a la dirección http://localhost/sf_sandbox/web/frontend_dev.php. A continuación, utiliza la línea de comandos de Symfony para instalar los dos plugins necesarios desde el respositorio de plugins de Symfony. Para ello, abre una consola de comandos en tu sistema operativo, vete al directorio en el que has descomprimido el sandbox (se llamará sf_sandbox) y ejecuta los siguientes comandos:

> php symfony plugin-install http://plugins.symfony-project.com/sfPropelVersionableBehaviorPlugin
> php symfony plugin-install http://plugins.symfony-project.com/sfAdvancedAdminGeneratorPlugin

El primer plugin requiere realizar un cambio en la configuración por defecto de Symfony, ya que en realidad es un behavior o comportamiento. Los comportamientos son modificaciones que se realizan al modelo de datos y que permiten añadir nuevas características a las clases del modelo en el que se utilizan. Para activar el uso de comportamientos en un proyecto Symfony, tienes que modificar la última línea del archivo de configuración config/propel.ini de manera que muestre lo siguiente:

propel.builder.AddBehaviors = true

Creando el modelo de datos

Un wiki consiste básicamente en una herramienta que permite gestionar artículos y que guarda todas las modificaciones realizadas sobre cada artículo. Por lo tanto, como mínimo se necesita una tabla llamada articulo para almacenar la información relativa a los artículos. El modelo de datos se define en el archivo de configuración config/schema.yml de la siguiente manera:

propel:
  articulo:
    id:         ~
    titulo:     varchar(255)
    cuerpo:     longvarchar
    version:    integer
    updated_at: ~

Utilizando solamente esta descripción, Symfony es capaz de inicializar la base de datos, crear las tablas necesarias y crear las clases de PHP que permiten trabajar con la base de datos utilizando una API orientada a objetos (cada clase se corresponde con una tabla de la base de datos). Para realizar todas estas tareas, sólo es necesario ejecutar el siguiente comando:

> php symfony propel-build-all

Por otra parte, el modelo de datos que corresponde a Articulo debe ser versionable, de forma que cada modificación que se realice genere una nueva versión del artículo. Gracias al primer plugin que has instalado, añadir esta característica al modelo de datos es tan sencillo como incluir la siguiente línea al final del archivo lib/model/Articulo.php:

sfPropelBehavior::add('Articulo', array('versionable'));

Como siempre que se crea una nueva clase, es necesario borrar la caché que genera Symfony para mejorar el rendimiento de la aplicación. Utiliza el siguiente comando para borrar la caché:

> php symfony clear-cache

En este punto, es recomendable que compruebes si la aplicación (que todavía no hace nada) sigue funcionando correctamente. Para ello, accede a la página inicial de la aplicación:

http://localhost/sf_sandbox/web/frontend_dev.php

Interfaz para crear y modificar artículos

A continuación, se utiliza la línea de comandos para crear un módulo llamado wiki, basado en el modelo de datos Articulo y creado con el generador de la parte de administración de las aplicaciones:

> php symfony propel-init-admin frontend wiki Articulo

Si has utilizado alguna vez el generador de administraciones, modifica su configuración hasta obtener un resultado satisfactorio. En otro caso, puedes copiar directamente la siguiente configuración en el archivo apps/frontend/modules/wiki/config/generator.yml:

generator:
   class:              sfAdvancedAdminGenerator
   param:
     model_class:      Articulo
     theme:            default

     list:
       title:        Listado de artículos
       sort:         titulo
       click_action: show
       display:      [=titulo, updated_at]
       filters:      [titulo, updated_at]
       object_actions:
         _show:      { name: Ver artículo }
         _edit:      { name: Editar artículo }
     show:
       actions:
         _list:      { name: Volver al listado }
         _edit:      { name: Editar artículo }
     edit:
       fields:
         updated_at: { type: plain }
         version:    { type: plain }
         cuerpo:     { params: size=80x15 }
       actions:
         _save:      { name: Guardar cambios }
         _show:      { name: Ver artículo }
         _list:      { name: Volver al listado }
         _delete:    { name: Borrar artículo }

Una vez guardada la configuración, accede a la siguiente URL para empezar a crear artículos de prueba:

http://localhost/sf_sandbox/web/frontend_dev.php/wiki

Puedes crear varios artículos de prueba y modificarlos varias veces. Cuando modifiques un artículo, verás que su número de versión se actualiza automáticamente (lo puedes ver en el campo version de la vista show). Esta es una de las granes ventajas de utilizar el plugin sfPropelVersionableBehaviorPlugin.

La configuración mostrada anteriormente hace uso de una extensión del generador de administraciones llamada sfAdvancedAdminGenerator. Esta extensión está disponible por haber instalado el segundo plugin llamado sfAdvancedAdminGeneratorPlugin. Este plugin ofrece una vista llamada show para ver los datos y separa las vistas create (para insertar datos) y edit (para modificar datos). En todo lo demás, la configuración sigue la sintaxis y opciones explicadas en el capítulo 14 del libro oficial de Symfony.

Historial de un artículo

Los wikis guardan todas las revisiones de los artículos y permiten consultar las versiones antiguas. Para crear esta característica, añade una acción llamada historial en el módulo wiki. Modifica la clase apps/frontend/modules/wiki/actions/actions.class.php y añade el siguiente método:

public function executeHistorial()
{
  $this->articulo = $this->getArticuloOrCreate();
}

Este método simplemente reutiliza un método que crea el generador de administraciones. El método getArticuloOrCreate devuelve un objeto de tipo Articulo en función de un parámetro de la petición llamado id. Si tienes curiosidad sobre cómo funciona este método, puedes encontrar la clase generada de forma automática en el archivo cache/frontend/dev/modules/autoWiki/actions/actions.class.php.

A continuación, es necesario crear la plantilla historial correspondiente a la acción anterior. Para ello, crea el archivo apps/frontend/modules/wiki/templates/historialSuccess.php con el siguiente contenido:

<?php use_stylesheet('/sf/sf_admin/css/main') ?>

<div id="sf_admin_container">
  <h1><?php echo sprintf('Historial de "%s"', $articulo->getTitulo()) ?></h1>
  <div id="sf_admin_content">

    <?php foreach ($articulo->getAllResourceVersions('desc') as $revision): ?>
    <div class="form-row">
      <?php echo sprintf("'%s', Versión %d, actualizada el %s (%s)\n",
        link_to($revision->getTitulo(), 'wiki/show?id='.$articulo->getId().'&version='.$revision->getNumber()),
        $revision->getNumber(),
        $revision->getCreatedAt(),
        $revision->getComment()
      ) ?>
    </div>
    <?php endforeach; ?>

    <ul class="sf_admin_actions">
      <li><?php echo button_to('Ver artículo', 'wiki/show?id='.$articulo->getId(), 'class=sf_admin_action_show') ?></li>
      <li><?php echo button_to('Editar artículo', 'wiki/edit?id='.$articulo->getId(), 'class=sf_admin_action_edit') ?></li>
    </ul>
  </div>
</div>

El método getAllResourceVersions() es una extensión del modelo disponible cuando se instala el plugin sfPropelVersionableBehaviorPlugin y devuelve un array de objetos de tipo ResourceVersion, cada uno de los cuales proporciona información sobre cada revisión.

Puedes acceder a la siguiente URL para ver el resultado de la nueva acción y su plantilla asociada:

http://localhost/sf_sandbox/web/frontend_dev.php/wiki/historial/id/1

Accediendo a la dirección anterior, se ve el historial de modificaciones del artículo cuyo id es igual a 1. Cada una de las revisiones muestra un enlace a la vista llamada show. De esta forma, es posible visualizar una versión concreta de cualquier artículo. Para que estos enlaces muestren la versión correcta, es necesario redefinir un método de la clase de la acción. Este nuevo método comprueba si la petición incluye un parámetro llamado version. En caso afirmativo, se muestra esa versión concreta del artículo:

protected function getArticuloOrCreate($id = 'id')
{
  $articulo = parent::getArticuloOrCreate($id);
  if($this->getRequest()->hasParameter('version'))
  {
    $articulo->toVersion($this->getRequest()->getParameter('version'));
  }

  return $articulo;
}

Con esta última modificación, ya se ha completado el funcionamiento básico del wiki. La página del historial se puede enlazar desde otras páginas del generador si se modifica el archivo generator.yml. Si quieres enlazarla en las vistas show y edit, añade lo siguiente bajo la clave actions:

_historial:   { name: Historial }

Conclusión

Si has seguido el tutorial, en menos de 50 líneas de código y en menos de 20 minutos has conseguido construir un wiki sencillo que permite buscar, ordenar y paginar sus contenidos. El wiki creado también permite visualizar (y reutilizar) cualquier versión anterior de un artículo. Por supuesto, para poder considerar tu wiki como una aplicación completa sería necesario que incluyeras al menos la autenticación de usuarios mediante el plugin sfGuardPluginy que se pudiera escribir el contenido de los artículos mediante un lenguaje de marcado tipo markdown. Para añadir estas dos características, seguramente necesitarás menos de 20 líneas de código.

En este tutorial has visto lo fácil que es crear una aplicación básica con Symfony. El framework y los plugins proporcionan las funcionalidades básicas y tu trabajo consiste en unirlos de forma que se adapten a tus necesidades. De cierta forma, este trabajo es similar a juntar bloques de LEGO para construir cualquier cosa que imagines. Además, como la aplicación tiene muy pocas líneas de código, su mantenimiento y actualización son muy sencillos.