Documentacion

1. Objetivo del script

Este script funciona como un mini explorador y editor web de archivos dentro del servidor.

Permite:

• Navegar carpetas desde una ruta base segura.
• Listar carpetas y archivos.
• Abrir archivos por URL directa.
• Editar contenido de un archivo desde un textarea.
• Reemplazar un archivo seleccionado mediante upload.
• Crear respaldo automatico antes de modificar.

2. Flujo general de trabajo

Flujo principal:

1. Detecta rutas base del servidor y la ruta actual del script.
2. Lee parametros GET para decidir carpeta actual y archivo a editar.
3. Valida seguridad de rutas para evitar salir de la base.
4. Si llega POST, ejecuta accion:
   • guardar_contenido
   • reemplazar_archivo
5. Lista carpeta actual separando carpetas y archivos.
6. Renderiza HTML con:
   • breadcrumb
   • enlaces de navegacion
   • listado
   • editor (si hay archivo seleccionado)

3. Bloques del codigo

Bloque 1. Rutas base y seguridad

Variables clave:

• $directorioActual: ruta fisica del script.
• $documentRoot: raiz web reportada por el servidor.
• $documentRootReal: version normalizada de DOCUMENT_ROOT.
• $directorioBase: limite superior permitido de navegacion.

Regla de seguridad:

• Si DOCUMENT_ROOT no es valido o no contiene la ruta del script, se usa la carpeta actual como base segura.

Bloque 2. Estado inicial

Variables:

• $rutaRelativaInicial: ruta relativa de la carpeta del script dentro de la base.
• $mensaje: texto de feedback para la vista.
• $tipoMensaje: ok o error.

Bloque 3. Lectura de GET dir

Parametro:

• dir: carpeta destino relativa.

Normalizacion:

• Reemplazo de backslash por slash.
• Limpieza de puntos y barras redundantes.

Bloque 4. Resolucion de carpeta objetivo

Variable:

• $directorioObjetivo: carpeta efectiva a listar.

Validaciones:

1. realpath debe resolver correctamente.
2. Debe ser directorio real.
3. Debe permanecer dentro de $directorioBase.

Si falla:

• Vuelve a carpeta del script.
• Genera mensaje de error.

Bloque 5. Ruta relativa actual

Variable:

• $rutaRelativaActual: usada para links, formularios y breadcrumb.

Bloque 6. Archivo a editar

Parametros:

• GET edit: archivo seleccionado en el listado.
• POST archivo_objetivo: archivo mantenido en formularios.

Validaciones:

1. Debe existir.
2. Debe ser archivo.
3. Debe estar dentro de la base permitida.

Bloque 7. Acciones POST

Acciones disponibles:

• guardar_contenido
• reemplazar_archivo

Pasos comunes:

1. Verificar permiso de escritura.
2. Crear respaldo .bak con timestamp.

Ruta guardar_contenido:

• Escribe texto con file_put_contents.

Ruta reemplazar_archivo:

• Lee archivo subido en $_FILES.
• Valida estado de upload.
• Sustituye con move_uploaded_file.

Bloque 8. Listado de directorio

Proceso:

1. Intenta scandir sobre carpeta objetivo.
2. Si falla, fallback a carpeta del script.
3. Si vuelve a fallar, usa arreglo vacio y muestra error.
4. Separa resultados en:
   • $carpetas
   • $archivos
5. Ordena alfabeticamente con sort.

Bloque 9. Navegacion

Elementos:

• Subir nivel: calcula ruta padre con explode, array_pop, implode.
• Breadcrumb: crea nodos acumulados para navegar por cada nivel.
• Atras y Adelante: usa history.back y history.forward del navegador.

Bloque 10. Construccion de URLs

Variables:

• $urlBaseServidor: esquema + host.
• $urlCarpetaActual: url publica de la carpeta actual.

Se usa:

• rawurlencode para caracteres especiales.
• reemplazo de %2F por / para mantener slashes legibles.

3.1 Glosario simple de terminos clave

• Resolver una ruta Significa convertir una ruta "relativa o ambigua" en una ruta real completa del sistema. Ejemplo: ./uploads/../users pasa a /var/www/server/miserver/users.

• Normalizar una ruta Significa dejarla en un formato consistente para compararla o usarla sin errores. Ejemplo: cambiar \ por /, quitar barras dobles y limpiar extremos.

• Ruta absoluta Es la ruta completa desde la raiz del sistema. Ejemplo Linux: /var/www/server/miserver/uploads.

• Ruta relativa Es una ruta calculada desde una base. Ejemplo: si la base es /var/www/server y estas en /var/www/server/miserver/uploads, la ruta relativa es miserver/uploads.

• Ruta base Es el limite superior permitido para navegar. El script no deberia salir de esta zona.

• Directorio objetivo Es la carpeta que el script intenta listar en ese momento. Cambia cuando haces click en Entrar o Subir nivel.

• Validar una ruta Es verificar que exista, que sea carpeta/archivo correcto y que no salga de la base.

• Path traversal Tecnica para intentar salir de la carpeta permitida usando ../ Ejemplo malicioso: ?dir=../../etc. El script lo bloquea validando realpath y prefijo de base.

• Fallback Es un "plan B" cuando algo falla. Ejemplo: si scandir falla en carpeta objetivo, intentar con carpeta del script.

• Sanitizar entrada Limpiar datos que vienen de usuario (GET, POST, FILES) antes de usarlos.

• Escapar salida Convertir caracteres especiales para que no se ejecuten como HTML/JS. Se hace con htmlspecialchars para prevenir XSS.

• Query string Parte de la URL despues de ? Ejemplo: ?dir=miserver/uploads&edit=index.php

• GET Metodo para enviar datos por URL (visible en la barra del navegador).

• POST Metodo para enviar datos por formulario (no visible en URL).

• Upload Subida de archivo desde el navegador al servidor.

• Respaldo o backup Copia de seguridad de un archivo antes de modificarlo. Ejemplo: index.php.bak.20260411_101530

• Timestamp Marca de fecha y hora usada para nombres unicos.

• Renderizar HTML Construir y enviar el contenido visual final que ve el navegador.

• Breadcrumb Ruta navegable por niveles, por ejemplo: server / miserver / uploads.

• Superglobales de PHP Variables especiales disponibles siempre, como $_GET, $_POST, $_SERVER, $_FILES.

4. Sintaxis PHP utilizada (explicada)

4.1 Estructuras de control

• if Evalua una condicion y ejecuta un bloque si es verdadera. Ejemplo: if ($ruta !== '') { ... }

• else Se ejecuta cuando la condicion del if no se cumple. Ejemplo: if ($ok) { ... } else { $mensaje = 'error'; }

• foreach Recorre elementos de un arreglo sin usar indices manuales. Ejemplo: foreach ($archivos as $archivo) { ... }

• continue Salta al siguiente ciclo del foreach. Ejemplo: si el item es . o .., se omite con continue.

4.2 Operadores

• === Comparacion estricta: mismo valor y mismo tipo. Ejemplo: $valor === false

• !== Diferente estricto: cambia valor o tipo. Ejemplo: $ruta !== ''

• ?: Operador ternario para asignaciones compactas. Sintaxis: condicion ? valor_si_true : valor_si_false Ejemplo: $esquema = $esHttps ? 'https' : 'http';

• . Concatenacion de cadenas. Ejemplo: $url = $base . '/' . $archivo;

4.3 Funciones de arreglos

• array() Crea un arreglo. Ejemplo: $carpetas = array();

• count($arr) Cuenta elementos del arreglo. Ejemplo: if (count($carpetas) === 0) { ... }

• sort($arr) Ordena el arreglo ascendente (alfabetico para strings). Ejemplo: sort($archivos);

• explode('/', $texto) Divide un string por separador y devuelve arreglo. Ejemplo: explode('/', 'a/b/c') => ['a','b','c']

• implode('/', $arr) Une arreglo en un string usando separador. Ejemplo: implode('/', ['a','b']) => 'a/b'

• array_pop($arr) Elimina y devuelve el ultimo elemento. Uso en el script: subir un nivel de carpeta quitando el ultimo segmento.

4.4 Funciones de strings

• trim($txt) Quita espacios al inicio y fin. Ejemplo: trim($_GET['dir'])

• ltrim($txt, $chars) Quita caracteres del inicio. Ejemplo: ltrim($ruta, '/\')

• strlen($txt) Longitud del string. Uso en el script: calcular desplazamiento para rutas relativas.

• substr($txt, $inicio) Extrae una parte del string. Ejemplo: substr($rutaAbs, strlen($base))

• str_replace($buscar, $reemplazo, $txt) Reemplaza texto literal. Ejemplo: str_replace('\', '/', $ruta)

• strpos($txt, $buscar) Busca posicion (sensible a mayusculas). Ejemplo: strpos($directorioActual, $documentRootReal) !== 0

• stripos($txt, $buscar) Igual a strpos, pero ignorando mayusculas/minusculas. Uso en el script: validacion flexible de prefijo de ruta.

• basename($ruta) Devuelve el nombre final de archivo/carpeta. Ejemplo: basename('/var/www/index.php') => 'index.php'

4.5 Funciones de archivos y rutas

• realpath($ruta) Resuelve ruta real y normaliza segmentos (.., enlaces, etc.). Devuelve false si no existe.

• is_dir($ruta) Verifica si la ruta es directorio.

• is_file($ruta) Verifica si la ruta es archivo.

• is_writable($ruta) Verifica permisos de escritura. Uso clave antes de guardar o reemplazar archivo.

• scandir($ruta) Lista contenido de una carpeta. Devuelve arreglo de nombres o false si falla.

• copy($origen, $destino) Copia archivos. Uso en el script: crear respaldos .bak antes de cambios.

• file_get_contents($archivo) Lee todo el contenido de un archivo como string. Uso: llenar el textarea de edicion.

• file_put_contents($archivo, $contenido) Escribe todo el contenido al archivo. Uso: guardar cambios del editor.

• move_uploaded_file($tmp, $destino) Mueve archivo subido desde ruta temporal de PHP. Uso: reemplazar archivo objetivo con upload.

4.6 Funciones de fecha

• date('Ymd_His') Genera timestamp para nombres unicos de respaldo. Ejemplo: archivo.php.bak.20260411_153000

4.7 Salida segura y URLs

• htmlspecialchars($txt, ENT_QUOTES, 'UTF-8') Escapa caracteres HTML para evitar XSS. Uso obligatorio al imprimir datos de usuario o rutas.

• urlencode($txt) Codifica texto para parametros de query string. Uso: ?dir=...

• rawurlencode($txt) Codifica texto para segmentos de URL. Uso: construir URLs de archivos/carpetas.

4.8 Superglobales usadas

• $_SERVER Informacion del entorno de ejecucion (host, document_root, request_uri, etc.).

• $_GET Parametros enviados por URL. Uso en el script: dir y edit.

• $_POST Datos de formularios enviados por metodo POST. Uso en el script: accion, contenido_archivo, archivo_objetivo.

• $_FILES Archivos subidos por formularios multipart/form-data. Uso en el script: archivo_reemplazo.

4.9 Constantes importantes

• DIRECTORY_SEPARATOR Separador de rutas segun sistema operativo. Windows: \ | Linux: /

• UPLOAD_ERR_OK Codigo de exito en subida de archivos. Se compara contra $_FILES['...']['error'].

4.10 Resumen rapido de seguridad sintactica

Reglas aplicadas en el script:

1. Validar rutas con realpath antes de usar.
2. Confirmar tipo de ruta con is_dir o is_file.
3. Validar permisos con is_writable antes de modificar.
4. Escapar salida HTML con htmlspecialchars.
5. Codificar parametros/segmentos URL con urlencode y rawurlencode.

5. Flujo de navegacion (ejemplo practico)

Escenario:

• Script ubicado en /var/www/server/miserver/uploads/TesteoServidor.php

Navegacion:

1. Carga inicial lista uploads.
2. Click en Subir nivel muestra contenido de miserver.
3. Aparecen carpetas esperadas, por ejemplo:
   • uploads
   • users
   • flags
4. Click en Entrar dentro de cualquier carpeta actualiza dir y vuelve a listar.
5. Click en breadcrumb permite saltar directo a nivel intermedio.

6. Flujo de edicion de archivo

1. En listado de archivos, click en Editar.
2. Se abre panel de edicion para ese archivo.
3. Opciones:
   • Guardar cambios del texto.
   • Reemplazar el archivo por upload.
4. Antes de modificar, genera respaldo automatico.
5. Muestra mensaje de exito o error.

7. Mensajes comunes y su significado

• La ruta solicitada no es valida: El parametro dir apunta fuera de la base o no existe.

• El archivo seleccionado para editar no es valido: El archivo no existe, no es archivo o sale del alcance permitido.

• El archivo no tiene permisos de escritura: Usuario web no puede modificar el archivo.

• No se pudo listar la carpeta actual: Falta permiso de lectura o ruta invalida.

• Error al subir archivo de reemplazo: Falla de upload, revisar php.ini y permisos temporales.

8. Recomendaciones de seguridad

1. Mantener esta herramienta solo en entorno controlado.
2. Restringir acceso por autenticacion.
3. Registrar acciones de edicion y reemplazo.
4. Revisar permisos minimos necesarios.
5. Desactivar display_errors en produccion.

9. Resumen tecnico

El script implementa un explorador web de archivos con enfoque practico:

• Validacion de rutas.
• Navegacion por carpetas.
• Edicion y reemplazo de archivos.
• Respaldo previo.
• Mensajes de estado.

Con esto tienes una base funcional para administracion de archivos dentro de una zona controlada del servidor.