Documentación continua en la nube

Tenemos Travis para integración continua, Scrutinizer para inspección continua… pero hasta hace unos días no existía un servicio para generar documentación continua de proyectos.

Para mí es un follón generar y subir a la web los phpDocs de mis proyectos de software libre cada vez que hago commit (ya que quiero tenerlos siempre actualizados); y también es un follón administrar y configurar Jenkins u otros servicios de integración continua para que generen los docs con cada build.

Así que he pensado que no sería tan complicado hacer un sistema que genere y aloje los documentos de mis proyectos en GitHub. Y si es útil para mí, también puede serlo para otros.

Dicho y hecho. Aquí lo tienes, tan sencillo como autorizar la aplicación en tu cuenta en GitHub y elegir qué repositorios quieres documentar. Cada vez que hagas push al repositorio, los documentos serán automáticamente generados y podrás verlos en github-phpdoc.israelviana.es/docs/[tu nombre de usuario GitHub]/[nombre del repositorio]:

Github-phpDocs landing page

Github-phpDocs landing repo list

GitHub-phpDoc documentación

Puedes probarlo ya en github-phpdoc.israelviana.es

El servicio es gratuito y open-source; por supuesto, el código está en GitHub y la documentación en la nube ;-)

De momento solo soporta proyectos en PHP alojados en GitHub (repositorios públicos de momento), pero si hay suficiente demanda se puede ampliar a otros lenguajes o alojamientos.

¿Y tú, generas documentación del código de tus proyectos? Si tienes proyectos PHP en GitHub te agradecería que probases el servicio y me dieras todo el feedback posible. ¡Gracias de antemano!

Y por último, una pregunta: ¿Estarías dispuesto a pagar 2€ por documentación privada de repositorios privados?

Tests de integración con Zarangotest

¿Cuántas veces hemos tenido que pelearnos con los ficheros de configuración a la hora de desplegar nuestro proyecto?

Respuesta: un montón. Y la mayoría de ellas, evitables.

La versión de PHP, las extensiones instaladas, los datos de conexión a la base de datos correctos… son algunas de las comprobaciones que debemos hacer cada vez que desplegamos una nueva versión de la aplicación. Y como es de bien nacidos automatizar los tests, algunos lo hacen con PHPUnit, otros de soluciones caseras… y otros usamos Zarangotest.

Zarangotest (cuyo nombre proviene del zarangollo, delicioso plato tradicional murciano) es un sencillísimo framework que podría haber escrito cualquiera, cuyos objetivos son organizar los tests (primordialmente los de integración), proporcionar una serie de tests ya escritos y presentar los resultados en una bonita página HTML.

Captura de un informe de Zarangotest
 ¿Cómo se usa Zarangotest?

Zarangotest, a diferencia de otros frameworks de test, está pensado para usar desde el servidor web, no desde la consola.

  1. Cargas el fichero de zarangotest: require_once ‘zarangotest.php’;
  2. Inicializas tus test según tus necesidades: cargar ficheros de configuración, declarar constantes…
  3. Declaras un array y lo vas rellenando de tests. Cada test es una instancia de la clase Zarangotest, y puedes especificar un título y una categoría (por si quieres agrupar tus tests para organizarlos mejor).
  4. Una vez declarado tu juego de tests, llamas a la función zarangotest($juegoDeTests, “Un título”).
<?php

include 'zarangotest.php';

$juegoDeTests = array();

/** Test Mysqli */
$juegoDeTests[] = new Zarangotest("Extensión mysqli", "Extensiones", function() {
    return function_exists("mysqli_close");
});

zarangotest($juegoDeTests, "MiProyecto");

Como puedes ver, el contenido de los tests consiste en una función anónima que devuelve true o false. Cualquier otro valor devuelto se considerará como un fracaso en la ejecución del test y se mostrará en el informe. Así pues, ejecutamos el script y obtenemos el informe:

Informe de Zarangotest

¿Y los tests pre-fabricados?

Zarangotest no está del todo terminado. Cuando lo esté, los tests prefabricados estáran disponibles como clases separadas. Mientras tanto, puedes utilizar el código de prefabricados.php.

¿Y esto no se puede hacer con PHPUnit?

Sí, se puede. Aunque PHPUnit está pensado para tests unitarios, se puede utilizar para hacer tests de integración e incluso tests funcionales. Pero si no dominas PHPUnit o no quieres/puedes desplegarlo en tus servidores, Zarangotest es una buena alternativa. Además, Zarangotest genera directamente el informe en HTML, algo que no es tan ágil con PHPUnit.

Es todo por el momento. En las próximas semanas iré subiendo actualizaciones, mejoras y más documentación a Zarangotest. Mientras tanto, sería genial que le echaras un vistazo y comentaras tus impresiones aquí :-)

Descargar Zarangotest

Relanzando Caminayven, otra historia de éxito con WordPress

Caminayven

Como comentaba en el artículo Primeras experiencias con WordPress… y muchas nueces ;-) , me estoy introduciendo en el mundillo de WordPress. Nueces San Ignacio no ha sido el único proyecto que he realizado con este gestor de contenidos. Hoy quiero contarte mi experiencia en otro proyecto un poco más grande: Caminayven. Se trata de una revista católica on-line, que lleva más de cinco años on-line sobre PHP-Nuke con más de mil artículos, un montón de redactores y, afortunadamente, un número creciente de visitas.

Hace dos años que empecé a trabajar en un nuevo gestor de contenidos para Caminayven. Empecé programando desde cero un CMS bastante ambicioso, y aproveché para hacer mis primeros pinitos con JavaScript-RPC (una especie de alternativa a AJAX para comunicación asíncrona, basada en carga dinámica de scripts e iframes). El resultado fue desastroso, aunque aprendí la valiosa lección de que no es bueno reinventar la rueda.

Pero —cabezón de mí— volví a la carga a principios del año pasado ayudado por CakePHP, un framework que me facilitó bastante las cosas, pero que seguía sin ser suficiente. Por falta de tiempo e ilusión el proyecto volvió a quedar abandonado, hasta que hace unos pocos meses empecé a preguntarme si WordPress cubriría las necesidades básicas de Caminayven: publicación de artículos, galerías de fotos, acceso sencillo y elegante a la información (archivos, destacados, relacionados…) y poco más.

De nuevo, un análisis realista y concreto de la Arquitectura de la Información para el proyecto puso las cosas en su lugar. ¿Para qué programar una gestión de usuarios, workflow, editor WYSIWYG, feed RSS, categorías y tags… si WordPress ya lo hace? Dicho y hecho: convertir las antiguas plantillas de CakePHP en un theme para WordPress fue cuestión de dos tardes (copiando y modificando Kubrick).

Aunque he tenido algunos problemillas en el theming, quizá causados por mi ignorancia sobre WordPress o por su estructura interna —en mi opinión poco elegante—: el formato de las fechas y la internacionalización. El formato de las fechas, aunque se especifica en el dashboard no se respetaba en el tema Kubrick, además de que los nombres de los meses no se traducen. Con respecto a la internacionalización (más concretamente la traducción), utilizo la versión en castellano de WordPress, pero aun así muchos mensajes están sin traducir, por lo que he tenido que traducir manualmente algunos fragmentos del theme.

En lo que respecta a la funcionalidad, he utilizado el plug-in Author Image y un código propio en el theme para mostrar, a la derecha de cada artículo, una breve ficha de su autor.

Galería

Caminayven también destaca por sus reportajes gráficos, la mayoría de ellos realizados por nuestro querido Javier Cebreros. Para publicarlos probé en primera instancia Awsom PixGallery. Aunque era sencillo utilizarlo y bonito ver una página para cada álbum/foto, el rendimiento es horrible (regenera continuamente las miniaturas), el código es patético (un único y monolítico script de miles de líneas, mezclando PHP y HTML) y el manejo de URL fallaba como una escopeta de feria. Ahora utilizamos NextGEN Gallery, que es justamente lo contrario: un buen rendimiento, mucha flexibilidad a la hora de subir fotos (subida múltiple por HTTP, FTP, etc) y una forma de mostrar los álbumes muy chula. Una posible mejora a este plug-in sería la construcción de colecciones a partir de álbumes en Flickr o Facebook (en Caminayven alojamos algunas fotos en estas redes sociales), y lo añado a mi lista de cosas-que-haré-algún-día.

Otros plug-ins

También he añadido WP-Cache y All-in-One-SEO-Pack para optimizaciones de rendimiento y SEO, respectivamente. Ambos funcionando muy bien y sin problemas. WP-Cache y los consejos de YSlow me han ayudado a hacer Caminayven más rápida, y aún se puede optimizar mucho más.

Migración

Hasta aquí la parte bonita. Pero no hay que olvidar que Caminayven es un proyecto de cierta envergadura y con una trayectoria de cinco años sobre PHP-Nuke, un gestor de contenidos que odio por ser el perfecto compendio de malas prácticas (de hecho, hace dos años nos colaron una inyección SQL que permitió a un niñato destrozarnos la página…). Así que la migración no se plantea fácil. Por una parte, los artículos se escribieron desde el editor WYSIWYG de Internet Explorer y desde Word, así que te puedes hacer una idea de la impeorable calidad del marcado HTML. No se puede copiar y pegar el contenido de una tabla de PHP-Nuke en otra de WordPress, así que la solución aparente está filtrando el HTML con unas decenas de expresiones regulares caseras y las funciones de inserción del API de WordPress. Además, las categorías han cambiado, y he tenido que hacer una tabla de “traducción” de las viejas a las nuevas categorías.

Y, por si fuera poco, nuestros artículos salen en Google News y perder las antiguas URL (modules.php…) sería desastroso para nuestro posicionamiento, tanto en Google News como en los buscadores en general. Así que ha habido que hacer redirecciones 301 e intentar encontrar el artículo por su antiguo ID… también he tenido que añadir el ID de los artículos a las URL, por exigencia de Google News (un poco caprichoso, sí).

Analítica y redes sociales

Al igual que con Nueces San Ignacio, mi trabajo en este proyecto ha ido más allá de lo puramente ingenieril, ya que he diseñado, redactado y otras actividades. Las dos más importantes para el éxito del proyecto han sido la analítica web y la promoción en redes sociales. En cuanto a lo primero, Google Analytics es una gran herramienta pero se está quedando corta para alguna información que necesito saber (los referer exactos cuando un usuario encuentra un error 404 o cosas así), así que estoy introduciendo pequeños códigos de seguimiento propios en la parte del servidor.

Con respecto a las redes sociales, hemos redefinido nuestra estrategia en Facebook, pasando de grupo a usuario corriente. El motivo primario es la visibilidad, ya que todas las novedades que publiquemos con el usuario Caminayven aparecerán en el timeline de nuestros amigos. En cuanto al contenido, enlazamos los artículos más destacables en el status, publicamos todos los posts con NetworkedBlogs y subimos los reportajes gráficos. La estrategia está funcionando en parte, ya que las visitas desde esta fuente han aumentado, pero nuestros seguidores (alrededor de 200) no son muy activos corriendo la voz… es decir, que la regla del 90-90-1 no se cumple del todo.

También nos hemos dado de alta en Twitter (@caminayven), aunque todavía no hay mucha actividad. Esperemos que en los próximos meses la cosa vaya aumentando.

Conclusiones

  • WordPress mola. No es la panacea, pero mola.
  • Hacer una revista católica en internet no es fácil, y crear una comunidad alrededor de la misma mucho menos, pero estamos en el camino.
  • Caminayven es un proyecto apasionante al que siempre se le puede sacar punta, quedan muchas cosas por hacer, pero de momento he cumplido con mi deber ;-)
  • La audiencia está respondiendo: las visitas, en general, han aumentado, y en particular, el promedio de páginas por visita. Pero, sobre todo, los comentarios, ese elemento mágico y maravilloso que da vida a un sitio web :-)

En fin, otro proyecto cerrado por el momento… dentro de un mes te cuento el siguiente… ¡más ambicioso y emocionante todavía!.

Primeras experiencias con WordPress… y muchas nueces ;-)

Web de Nueces San Ignacio
Todo desarrollador web debe saber trabajar con uno o varios sistemas de gestión de contenidos (CMS). Estos programas nos ahorran reinventar la rueda cada vez que tenemos que publicar contenidos en la web, gestionar usuarios y la administración del sitio, organizar nuestro código de acuerdo a un estándar, etc, etc, etc.

Personalmente siempre he sido aficionado a los CMS, pero a nivel de usuario. Me encanta conocer y probar los gestores de contenido, aunque hasta hace poco no había desarrollado proyectos —proyectos de verdad— con una de estas herramientas, por vagancia para afrontar la curva de aprendizaje y por afán de reinventar la rueda (puede ser divertido y muy pedagógico, pero no es práctico si queremos buenos resultados).

El caso es que hace un par de meses comencé un proyecto web para un amigo que cultiva nueces y me animé a probar WordPress, animado por la experiencia de los chicos de Atracciona, que utilizan este gestor de blogs para hacer webs corporativas. Mi proyecto era dar presencia web a la Nueces San Ignacio y captar clientes a través de Internet, por lo que a nivel técnico las exigencias eran mínimas (unas cuantas secciones de texto rico, fotos, un formulario de contacto y poco más).

La experiencia con WordPress ha sido impresionante. A pesar de que no me gustan sus tripas (algunos fragmentos de código son verdadero spaghetti code), diseñar un theme con WordPress es increíblemente fácil y rápido. Una vez tuve el diseño en HTML/CSS, pasarlo a WordPress fue cosa de una noche. No toma más esfuerzo que copiar un tema (por ejemplo, Kubrick) e ir modificando las plantillas, adaptando el CSS y cambiando el marcado que sea necesario.

El resultado, una web corporativa con un panel de administración muy potente, la disponibilidad de miles de plug-ins y el respaldo de un software probado en millones de servidores.

Logo de Nueces San IgnacioMás allá de la programación, también diseñé la web, el logotipo —y las tarjetas de visita, y un dossier comercial, todo ello con software libre e imágenes libres— y todo lo relativo a márketing en redes sociales, SEO y SEM. Y aunque el mercado en el que se mueve la empresa no depende en gran medida de Internet (el objetivo es vender toneladas de nueces, y el público objetivo hoy en día son distribuidores y grandes superficies), poco a poco la estrategia web va dando fruto. La experiencia ha sido gratificante, porque no es lo mismo hacer un proyecto para un cliente (con la exigencia de calidad y la concentración de sólo programar) que para un amigo (he tenido total libertad para diseñar, desplegar, redactar, etc). Te lo tomas con más calma, le dedicas las horas que puedas y el resultado acaba siendo muy satisfactorio, porque de un modo u otro me he involucrado en la empresa.

Conclusión, WordPress es un muy buen gestor de blogs que también puede ser usado como gestor de contenidos genérico para sitios web pequeños, con una rapidez en la creación de themes que nunca antes se había visto. No obstante, cuando tenga tiempo he de revisar otros CMS para sitios web corporativos. Hace algún tiempo probé CMS Made Simple, pero no me convenció. Sin embargo, MODx promete bastante.

Cuestiones todas a resolver en 2010. Feliz Navidad y que el año que se avecina sea el mejor de tu vida :-)

MagiSQL ha muerto

Hace cerca de un año que comencé un proyecto llamado MagiSQL, con el objetivo de crear una herramienta modular de gestión de bases de datos relacionales, compatible con múltiples sistemas de BBDD y con licencia libre, por supuesto.

Me he planteado muchas veces la viabilidad y utilidad del proyecto, ya que la competencia es muy dura (phpMyAdmin, pgAdmin, Oracle Enterprise Manager, etc etc etc) y exige reinventar la rueda en la mayoría de los módulos. Además, para que el proyecto fuese exitoso no sólo era necesario que me dejase los ojos durante muchas horas, sino que más programadores se sumasen al proyecto y desarrollasen módulos compatibles con los sistemas gestores de bases de datos, ya que yo no tengo tiempo ni medios para hacer MagiSQL compatible con Oracle, MS-SQL Server, PostgreSQL, MySQL y DB2, como está planteado en los objetivos del proyecto (de momento sólo funcionaba con MySQL). Además, este verano he reescrito por completo el núcleo, lo que ha retrasado y complicado aún más el desarrollo.

Por estos motivos y muchos otros (baja productividad, falta de tiempo y concentración, cuestiones personales…) he decidido no continuar el proyecto. Nunca ha alcanzado un nivel de madurez mínimo como para ser usable, y la gran parafernalia de módulos, clases y patrones hace bastante inútil el código que hay en mi disco duro y en el SVN de Sourceforge. En resumen, que se irá todo a la basura.

¿Todo? Eso significaría tiempo perdido, derrota, fracaso. Y aunque no deja de serlo, es un fracaso del que estoy orgulloso y del que he aprendido un montón, entre otras cosas:

  • He ideado el patrón de diseño “Application Status”, del que tendréis más noticias dentro de algún tiempo… ;-)
  • Me he acostumbrado a escribir documentación en línea (phpDoc) y en inglés.
  • Me he familiarizado con la biblioteca AdoDB.
  • Me he hartado de Smarty. Era el último proyecto en el que lo usaba, y desde ahora sólo utilizaré plantillas PHP.
  • He aprendido más cosas sobre la reescritura de URL y expresiones regulares.
  • He comprendido e implementado multitud de patrones.
  • Me he familiarizado con las excepciones de PHP y los métodos mágicos.
  • He explotado las novedades de PHP 5.3.
  • He encontrado un buen entorno de programación en PHP sobre Linux (Netbeans, KCacheGrind, etc).
  • Me he convencido una vez más de que reinventar la rueda es friki, divertido pero inútil y bastante frustrante.
  • He escuchado cientos de discos mientras hacía todo eso ;-)

Bueno ¿y ahora, qué? Ya que el proyecto era para una asignatura de la carrera (aprovecho para decir que, tras pasar al Grado en Informática en la UCAM, he tenido que volver a matricularme de una asignatura que ya tenía aprobada), será sustituido por un motor de almacenamiento en MySQL para Object Freezer. Object Freezer es una biblioteca escrita por Sebastian Bergmann para almacenar objetos en la base de datos CouchDB sin preocuparse de SQL, DAO y demás inventos del pasado ;-)