Marco de herramientas web con PHP

Con un marco de herramientas web en localhost podemos hacer cosas como modificar contenidos de forma genérica, analizar los documentos HTML para ver si están bien construidos, localizar vínculos rotos, construir índices para un buscador, construir el sitemap o el robots.txt, etc. La idea general se basa en construir módulos PHP escalables que funcionan apoyándose unos en otros. Así por ejemplo existe el módulo básico llamado comun.php desde donde se inicia el marco de herramientas. Luego tenemos otros también básicos como explorador.php y visor-ficheros.php que claramente sirven para explorar por carpetas y archivos y seleccionarlos o, en el otro caso, como un visor de archivos de texto. A partir de esa base vamos agregando herramientas con una estructura similar con relativa facilidad. En resumen, esto que empezó como una aplicación a modo de ejercicio para practicar con PHP, ahora ya es algo imprescindible para desarrollar mi sitio.

Hasta ahora he ido aportando en este sitio algunas herramientas pero de forma aislada, es decir, desintegrándolas del marco. El motivo es que aún tenía que perfilar algunas cosas antes de exponerlo aquí. Pero ese aislamiento me suponía un doble trabajo, pues aunque desarrollaba una herramienta dentro del marco, luego tenía que extraerla para que pudiera funcionar de forma aislada. Bueno, pues ahora voy a presentar este marco y así podré publicar aquí las herramientas que tengo ya en funcionamiento y otras nuevas con el mínimo esfuerzo posible.

El conjunto de módulos PHP operan mediante una interfaz HTTP, es decir, se usan páginas HTML con formularios para la interfaz. Entonces envíamos los datos de la interfaz al servidor local, que tras procesar lo necesario usando los módulos, nos devuelve también por HTTP el resultado. Tengo montado mi servidor local con Apache bajo Windows, recurso con el que pruebo las páginas antes de subirlas a este sitio, también un servidor Apache. Por lo tanto este marco de herramientas también debería funcionar en este sitio. Pero hay que entender que sólo está preparado para funcionar en localhost por varias razones. La primera es por motivos de seguridad, pues en ningún momento tengo en cuenta el filtrado de datos recibidos en el servidor en relación con XSS, CSRF, etc. Pero quizás la razón más importante es el elevado consumo de recursos que necesitan algunos procesos. No tendría sentido forzar el servidor en producción para ejecutar procesos de herramientas que podemos hacer con total libertad de recursos en modo local. Y sobre todo, sin entorpecer el tráfico de nuestro sitio en producción. Después de todo el objetivo final de cada herramienta es obtener un resultado que, o bien subiremos a nuestro sitio en producción (como robots.txt), o bien servirán para arreglar cosas del mismo (como localizar vínculos rotos).

Estructura de carpetas del marco de herramientas

Puedes descargar tools-web.zip que contiene lo básico para instalar las carpetas del marco de herramientas. Ocupa unos 82 KB y tiene esta estructura:

• /no-publicable/tools-web
  • /includes
    • /comun.php
    • /conf.php
    • /explorador.php
    • /ficheros.php
    • /tools.js
  • /piezas
    • /explorador
      • /conf.txt
      • /index.php
    • /indice
      • /conf.txt
      • /index.php
    • /telnet
      • /conf.txt
      • /index.php
    • ...OTRAS HERRAMIENTAS...
  • /res
    • /formatos.css
    • /general.js
    • /icon.ico
    • /wextensible.gif
  • /styles
    • /tools.css

De entrada he de decir que uso Apache 2.2.15 más PHP 5.2.13 en mi localhost. Para instalar este marco hay que crear una carpeta no-publicable en la carpeta raíz del sitio local. En otras ocasiones he comentado que tengo la misma estructura de carpetas del sitio en localhost que la que hay en producción. A excepción de la carpeta /no-publicable. Como su propio nombre indica almacena contenidos que no se publican en el sitio en producción. Entonces en esa carpeta se descomprime el zip quedando como la estructura anterior. La ruta /no-publicable/tools-web/piezas/indice/ nos abrirá el índice del marco, es decir, nos mostrará de forma automática este listado de todas las herramientas disponibles ordenado alfabeticamente. Se observa en la captura de pantalla de la izquierda que los nombres de esta lista son tomados literalmente de la lista de carpetas que hay en piezas. Por lo tanto cuando se agrega una nueva pieza el índice se actualiza automáticamente. Esta captura de pantalla la he realizado dimensionando la ventana del navegador para que salgan las tres pestañas Índice, Opciones y Mensajes en una imagen pequeña. En cómo se hace un contenedor con pestañas en cuerpos de tabla puede ver como funciona esto de las pestañas, pues puede aplicarse a otros cometidos del sitio web.

La carpeta de includes contiene los módulos de procesos que en definitiva son los que realizan las acciones de cada herramienta. Por ejemplo, el módulo comun.php es llamado por todas las herramientas pues contiene algunas funciones y declaraciones de uso común. El módulo conf.php se destina a gestionar las configuraciones. Había dicho más arriba que se usa una interfaz mediante un formulario HTML que envía los datos a procesar y el marco nos devuelve un resultado. Pues bien, esos datos se almacenan en un archivo de configuración para cada herramienta. Son los conf.txt cuya lectura y escritura se gestiona en ese módulo conf.php. En definitiva, en includes ponemos los módulos de proceso y también, si fuera el caso, los JavaScript como ese tools.js. En este caso se trata del script que maneja algunas cosas de la interfaz HTML.

En la carpeta /piezas están las interfaces de cada herramienta. Como mínimo cada una contiene un archivo conf.txt y un index.php, que es el HTML con el script PHP que recibe el formulario con los datos de la petición y devuelve el resultado y mensajes. La carpeta styles contiene las hojas de estilo CSS para el marco. La carpeta res tiene un propósito diferente. Los recursos que he puesto ahí realmente los tengo localizados en otro lugar, pues son recursos genéricos para el sitio. La hoja formatos.css da estilo al sitio mientras que general.js es un script de recursos básicos. Las imágenes también son del sitio más que de la herramienta. Pero para que pueda utilizar este marco he tenido que ubicar una copia dentro de esta estructura. Aunque esto puede cambiarse en la configuración de la herramienta indice.

En esta primera entrega he puesto la herramienta Telnet que ya hace tiempo había presentado en forma aislada en Telnet con PHP. Ya forma parte de este marco y servirá para comprobar, en caso de que decida probar todo esto, si el conjunto de herramientas funciona como se espera. En entregas siguientes iré aportando nuevas herramientas de tal forma que sólo hay que ubicar los archivos en alguna de las carpetas anteriores, especialmente en includes, piezas y res.

Los archivos de configuración conf.txt

Los archivos de configuración son los conf.txt, archivos de texto que contienen datos que configuran cada herramienta. Se gestionan con el módulo conf.php. Por ejemplo, el que contiene la configuración común y que se presenta en la interfaz del índice se reproduce parcialmente a continuación para explicar su estructura:

#--------------------------------------------------
# Configuración general /indice/conf.txt
#--------------------------------------------------

#String: ruta de un icono del sitio
icon-ico=/no-publicable/tools-web/res/icon.ico

...

#Booleano: Mostrar mensajes de proceso
mp=1

....

#Real: Segundos de ejecución en servidor. Se actualiza en PHP con 
#la configuración set_time_limit()
timeout=30

...

#Array: archivos index del servidor
archivos-index=index.html,index.php

En el contenido los comentarios empiezan con el caracter #. Esto es igual a como funcionan los archivos de configuración de PHP, por ejemplo. Pero aquí sólo encontramos campos de datos, que en definitiva se convertirán en variables PHP. Aunque en ningún momento hace falta editar manualmente los archivos de configuración, puede ser conveniente explicar un poco la estructura de las parejas campo-valor. El formato es algo como nombre_campo = valor_campo\n, donde \n representa un salto de línea. Digamos que cada línea del archivo de texto que no sea un comentario o una línea vacía o sólo con espacios blancos ha de ser una pareja campo-valor si obedece al patrón [^=]+\s*=[\n]* que coincidiría con un principio y fin de línea, es decir, con cada línea del archivo. Realmente no uso expresiones regulares para recuperar los campos, pero lo anterior puede explicarlo.

El nombre es cualquier cadena de uno o más caracteres que no contenga el signo igual. Aunque no se limita los caracteres a usar, hay que tener en cuenta que esos nombres de campos luego pasan a formar parte de los atributos id y/o name del formulario de la interfaz. Por lo tanto deben obedecer la regla de nombres para esos atributos. Luego viene cero o más espacios, el signo igual y cero o más caracteres hasta el salto de línea. En esta parte del valor todo lo que hay, incluso los espacios iniciales forman parte del mismo. Se escapan algunos caracteres como el propio salto con %CRLF, el caracter $ con %DLR y la coma con _COMA_. Estos escapes, que también se pueden configurar como veremos más abajo, tienen la particularidad de que los dos primeros son transparentes para el usuario. Es decir, los escapes del salto de línea y del caracter $ se producen al leer y escribir la configuración pero no cuando los editamos en el formulario. En cambio el escape de la coma si hay que especificarlo en los campos de lista (lo veremos después). En la interfaz de cada herramienta se dispone de la declaración de un array que equivale a este archivo de configuración:

Este array se inicializa siempre para cada herramienta poniendo como valores iniciales los tipos que correspondan a cada dato. Así los tipos string se inicializan con una cadena vacía "", los booleanos con el valor false, los números reales con 0.0, los números enteros con 0 y los array con array(""). Estos últimos son listas de string separados por comas en el archivo de configuración, sin espacios entre las comas. Cuando necesitemos incluir la coma uraremos el escape _COMA_. Este escape y otras variables globales y constantes comunes se declaran en el módulo comun.php. A continuación se expone el código del inicio de ese módulo:

Opciones y mensajes de una herramienta

En cada herramienta hay al menos una pestaña de mensajes pues los procesos encadenan mensajes que pueden ser de proceso (color negro), información (verde), aviso (naranja) o error (rojo). Que aparezcan o no se puede configurar en las opciones como se observa en la captura de pantalla más abajo. También se resalta con color azul todo lo que esté entrecomillado. Estos mensajes se toman en puntos claves del proceso e informan de lo que está pasando en cada momento. Son una gran ayuda para localizar errores en los procesos. Los datos de configuración son una entrada a la herramienta y usualmente los reparto en las otras pestañas, como en este caso en Visor y Opciones. Pero también otras herramientas tienen una pestaña de Resultado, pues a veces el proceso devuelve un texto con información o el propio producto final que queremos obtener con la herramienta.

En cuanto a la configuración común hay un par de detalles que conviene explicar. Esta captura se encuentra en las Opciones de la herramienta del índice. Aparte de la configuración de los mensajes y de la zona horaria (puede ver su zona en timezones), está lo relacionado con los tiempos de ejecución, que viene a ser uno de los puntos críticos al usar un servidor Apache montado como localhost con PHP para gestionar herramientas.

PHP tiene una limitación en tiempo en la ejecución de un script para evitar colapsar el servidor. Por defecto suele venir con 30 segundos. Además Apache tiene también una limitación que normalmente se establece en 300 segundos. Pero para la ejecución de herramientas en localhost en ciertos casos hemos de saltarnos estas limitaciones. En principio ninguno de los procesos simples debería durar más de 30 segundos. Si fuera así es que algo no está funcionando bien. Al llegar a ese límite PHP emitirá un aviso que será enviado al navegador. Recuerde que en un servidor montado en localhost para practicar no debemos desactivar la configuración de PHP (el archivo php.ini) para que no se muestren los errores, pues lo que queremos es verlos para poder arreglarlos. No pasa así en un servidor en producción, donde se ocultan todos los avisos por motivos de seguridad. Para los procesos más complejos, que denomino procesos largos, dispongo de un módulo paginador que, probablemente, expondré en el futuro para que pueda descargarlo. Las configuraciones de paginar resultados cada... y comprobar desconexión cada... son para esos procesos que usen el módulo paginador. En las herramientas entregadas con la descarga actual no hay ningún proceso largo, por lo tanto esos dos campos no tendrán ningún efecto. Pero el primer campo máximo tiempo de ejecución en el servidor sí que aplica a los procesos simples. Con valor 0 PHP no aplica ningún límite de tiempo de ejecución, pero siempre es aconsejable usar un valor de al menos 30 segundos para evitar, por ejemplo, un cuelgue de un bucle que por cualquier motivo esté funcionando mal.

Por ahora no voy a extenderme explicando más detalles del marco de herramientas. Espero en breve ir incorporando piezas de herramientas a este marco.