En más de una oportunidad me encontré con la necesidad de administrar archivos desde el navegador sin depender de soluciones pesadas o demasiado acopladas al framework de turno. A partir de esa necesidad nació FilesExplorer, una librería PHP pensada para listar, subir, descargar, renombrar, mover y compartir archivos mediante una interfaz web moderna y una lógica desacoplada de la capa HTTP.
El objetivo desde el principio fue construir un explorador de archivos reutilizable, fácil de integrar y suficientemente flexible como para funcionar tanto en una demo simple como dentro de un sistema con autenticación y permisos propios.
Objetivo del proyecto y tecnologías utilizadas
FilesExplorer fue desarrollado principalmente con PHP y JavaScript. En el backend la idea fue encapsular la lógica de negocio en una clase namespaced y compatible con PSR-4, mientras que en el frontend se trabajó con JavaScript y Bootstrap 5 para resolver la interfaz y los componentes visuales.
Más que crear un simple administrador de archivos, la intención fue proponer una base técnica ordenada: una librería que no leyera directamente $_POST, no enviara headers por sí sola y tampoco dependiera de sesiones.
Arquitectura y funcionalidades principales
El enfoque utilizado fue separar el sistema en tres capas bien definidas: interfaz cliente, controller HTTP y núcleo de la librería. El frontend renderiza el listado y las acciones disponibles. El controller recibe la petición, configura la librería y decide si la respuesta debe ser JSON o binaria. Finalmente, el core ejecuta la operación sobre el sistema de archivos y retorna un resultado estructurado.
$explorer = new \Richard\FilesExplorer\FilesExplorer($config);
$result = $explorer->execute($_POST, $_FILES);Entre las funcionalidades principales que quedaron implementadas destacan:
- Listado de archivos y carpetas.
- Subida de archivos mediante formularios y multipart/form-data.
- Descarga de archivos con respuesta binaria controlada por el controller.
- Creación de carpetas, renombrado y movimiento de elementos.
- Generación de enlaces compartidos.
- Interfaz con vista de lista y cuadrícula.
Desafíos técnicos encontrados
Uno de los desafíos más importantes fue evitar el acoplamiento clásico entre lógica de negocio y capa web. En versiones antiguas de este tipo de componentes es común que la misma clase lea variables globales, imprima salidas y termine la ejecución con exit. Aunque eso funciona en demos rápidas, se vuelve difícil de testear cuando el proyecto crece.
Otro punto crítico fue la seguridad. Al trabajar con rutas y nombres de archivos, era indispensable prevenir problemas como path traversal, caracteres peligrosos, accesos fuera del directorio base y operaciones no autorizadas. También fue necesario resolver correctamente el caso especial de las descargas, ya que no comparten el mismo flujo de respuesta que las acciones JSON tradicionales.
Solución implementada
La solución fue diseñar un núcleo agnóstico de HTTP que recibe arreglos simples como entrada y devuelve arreglos estructurados como salida. El controller actúa como intermediario, por lo que la autenticación, los headers y la forma de responder quedan bajo control del proyecto que integra la librería.
let explorer = new FilesExplorer('files_container');
explorer.setServerController('controller.php');
explorer.start();En el núcleo se incorporaron validaciones para sanitizar entradas, verificar acciones permitidas, normalizar rutas y construir paths seguros dentro del directorio base. En paralelo, el frontend fue organizado con una UI más clara, incorporando modales, acciones contextuales y dos modos de visualización.
Aprendizajes obtenidos y conclusión
El desarrollo de FilesExplorer me dejó varios aprendizajes importantes. El primero es que incluso una herramienta aparentemente simple puede volverse mucho más robusta cuando se diseña con separación de responsabilidades desde el inicio. El segundo es que la seguridad no debe tratarse como un agregado posterior.
En conclusión, FilesExplorer terminó convirtiéndose en algo más que una interfaz para gestionar archivos: fue un ejercicio práctico de arquitectura, reutilización y diseño orientado a integración. Todavía existen muchas posibilidades de expansión, pero la base ya permite resolver un problema real con una estructura ordenada y fácil de adaptar.
Repositorio:
https://github.com/RichardCollao/FilesExplorer