Exportación a Excel

Módulo: Shared/General Tipo: Utility Estado: Implementado Fecha: 2025-12-12

---

Descripción

El sistema de informes soporta exportación a formato Excel (.xlsx) además del formato PDF por defecto. Esta funcionalidad permite a los usuarios obtener los datos tabulares de los informes en un formato que facilita el análisis, filtrado y manipulación de datos en herramientas de hojas de cálculo.

La exportación Excel es especialmente útil para:

• Análisis de datos con filtros avanzados
• Generación de reportes personalizados
• Integración con sistemas externos
• Procesamiento masivo de información

---

Arquitectura

Componentes principales

La funcionalidad de exportación Excel está implementada en:

Archivo	Descripción
util/excel.php	Funciones helper para creación y envío de Excel
util/methods.php	Función formatNameFile() con soporte para extensión xlsx

Funciones disponibles

crearExcel(array $encabezado, array $cuerpo): string

Crea un archivo Excel en memoria y retorna su contenido binario.

Parámetros:

• $encabezado: Array de columnas con estructura:

  [
      ['nombre' => 'Nombre Columna', 'tipo_filtro' => 'fecha'|null],
      ['nombre' => 'Otra Columna', 'tipo_filtro' => null],
      // ...
  ]

• $cuerpo: Array de filas con datos (array bidimensional)

Retorna: Contenido binario del archivo Excel

Ejemplo:

$encabezado = [
    ['nombre' => 'Fecha', 'tipo_filtro' => 'fecha'],
    ['nombre' => 'Cliente', 'tipo_filtro' => null],
    ['nombre' => 'Monto', 'tipo_filtro' => null],
];

$cuerpo = [
    ['2025-01-15', 'Cliente A', 1500.00],
    ['2025-01-16', 'Cliente B', 2300.50],
];

$excelContent = crearExcel($encabezado, $cuerpo);

enviarExcel(string $content, string $fileName = 'reporte'): void

Envía la respuesta HTTP con el archivo Excel generado.

Parámetros:

• $content: Contenido binario del Excel (resultado de crearExcel())
• $fileName: Nombre del archivo sin extensión

Ejemplo:

$content = crearExcel($encabezado, $datos);
enviarExcel($content, 'informe-ventas');
// Genera: informe-ventas_2025-01-15_14-30.xlsx

debeGenerarExcel(array $array): bool

Determina si el informe debe generarse en formato Excel basado en el parámetro formato del request.

Parámetros:

• $array: Array de parámetros del request

Retorna: true si formato === 'excel', false en caso contrario (PDF por defecto)

Ejemplo:

if (debeGenerarExcel($array)) {
    // Generar Excel
    $content = crearExcel($encabezado, $datos);
    enviarExcel($content, 'reporte');
} else {
    // Generar PDF (flujo normal)
    include 'template.php';
    // ...
}

---

Uso desde el Frontend

Request para PDF (por defecto)

{
    "codReporte": 402,
    "filtros": {
        "fechaDesde": "2025-01-01",
        "fechaHasta": "2025-01-31"
    }
}

Request para Excel

{
    "codReporte": 402,
    "formato": "excel",
    "filtros": {
        "fechaDesde": "2025-01-01",
        "fechaHasta": "2025-01-31"
    }
}

Parámetro formato

Valor	Resultado
Omitido	PDF (por defecto)
"pdf"	PDF
"excel"	Excel (.xlsx)

---

Características del Excel generado

Autofiltros

El Excel se genera con autofiltros habilitados en todas las columnas, permitiendo al usuario filtrar datos directamente desde Excel.

Filtros de fecha

Las columnas marcadas con tipo_filtro: 'fecha' tienen habilitado el filtro por grupos de fecha (día, mes, año) nativo de Excel.

$encabezado = [
    [
        'nombre' => 'Fecha Operación',
        'tipo_filtro' => 'fecha'  // Habilita filtro por fecha
    ],
    // ...
];

Formato de fechas

Las fechas en formato ISO (YYYY-MM-DD) son convertidas automáticamente al formato de fecha nativo de Excel, permitiendo ordenamiento y filtrado correcto.

---

Consideraciones técnicas

Dependencias

• PhpOffice/PhpSpreadsheet: Biblioteca para generación de archivos Excel
  • Versión: Verificar en composer.json
  • Documentación: https://phpspreadsheet.readthedocs.io/

Performance

• Los archivos Excel se generan en memoria usando buffer de salida
• Para conjuntos de datos muy grandes (>10,000 filas), considerar:
  • Paginación de resultados
  • Generación asíncrona
  • Límites de timeout del servidor

Memoria

El archivo se genera completamente en memoria antes de enviarse. Para informes muy grandes, asegurar que memory_limit de PHP sea suficiente.

Headers HTTP

La función enviarExcel() establece automáticamente:

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename=nombre_YYYY-MM-DD_HH-MM.xlsx

---

Ejemplo de implementación completa

case 'mi-informe':
    try {
        $database = new Database($db, $schema);
        $conn = $database->getConnection();

        // Obtención de datos (siempre necesaria)
        include 'reports/mi-modulo/mi-informe-datos.php';

        if (debeGenerarExcel($array)) {
            // Ruta Excel: solo necesita los datos
            $encabezado = [
                ['nombre' => 'Fecha', 'tipo_filtro' => 'fecha'],
                ['nombre' => 'Cliente', 'tipo_filtro' => null],
                ['nombre' => 'Importe', 'tipo_filtro' => null],
            ];

            $content = crearExcel($encabezado, $datos);
            enviarExcel($content, 'mi-informe');
        } else {
            // Ruta PDF: necesita renderizar HTML
            ob_start();
            include 'reports/mi-modulo/mi-informe-render.php';
            $html = ob_get_clean();
            $html = formatearPagina($html, TipoPagina::A4);

            $pdfGenerator = new PdfGeneratorService();
            $result = $pdfGenerator->generatePdf($html);

            header('Content-Type: application/pdf');
            header(formatNameFile('mi-informe'));
            echo $result;
        }
    } catch (Exception $e) {
        ExceptionHandler::handle($e);
    }
    break;

---

Relación con la arquitectura de informes

Ver también: Arquitectura de Informes

La exportación Excel se integra con el patrón de separación datos/render:

reports/
└── mi-modulo/
    ├── mi-informe-datos.php    # Obtención de datos (usado por PDF y Excel)
    └── mi-informe-render.php   # Renderizado HTML (solo para PDF)

Esta separación permite que:

1. Excel: Use solo el archivo -datos.php
2. PDF: Use ambos archivos (-datos.php + -render.php)

---

Historial de cambios

Fecha	Versión	Autor	Descripción
2025-12-12	1.0	Sistema	Implementación inicial con funciones helper