hqsoft / reportkit

1.0.4 2026-06-04 02:42 UTC

Requires

• mpdf/mpdf: ^8.2
• openspout/openspout: ^5.3
• phpoffice/phpspreadsheet: ^5.2

MIT

• Hugo Quijada

• php
• excel
• csv
• pdf
• layout
• reportes

Published on Packagist.org on 2026-06-04 02:43 UTC

README

Librería PHP para definir documentos una sola vez mediante una estructura neutral basada en filas, columnas y celdas, y luego renderizarlos en múltiples formatos. El namespace principal del proyecto se mantiene como hqsoft\reportkit.

Actualmente incluye renderers para HTML, PDF, Spreadsheet y CSV, con una arquitectura pensada para seguir creciendo hacia Word / DOCX sin acoplar el documento a una librería específica.

Instalación

composer require hqsoft/report-kit

Uso Básico

La clase principal es Document, donde defines la estructura de tu reporte mediante filas (Row) y columnas (Column) sobre un grid configurable de 24 columnas.

use hqsoft\reportkit\document\Document;

// Crear un documento nuevo
$doc = new Document();

// Agregar un título (fila de ancho completo)
$doc->row(function($row) {
    $row->col(24)->text('Mi Reporte Mensual')->align('center'); // 24 columnas es el ancho total por defecto
});

// Agregar encabezados
$doc->header(function($row) {
    $row->col(8)->text('Producto', true);
    $row->col(8)->text('Cantidad', true);
    $row->col(8)->text('Precio', true);
});

// Agregar datos
$doc->row(function($row) {
    $row->col(8)->text('Laptop');
    $row->col(8)->text('10');
    $row->col(8)->text('1500.00');
});

Renderizado

Una vez definido el documento, puedes usar diferentes "Renderers" para generar la salida deseada.

HTML

Genera una tabla HTML con estilos en línea, ideal para vistas previas o correos.

use hqsoft\reportkit\renderers\html\HtmlRenderer;

$renderer = new HtmlRenderer();
echo $renderer->render($doc);

Spreadsheet (Excel)

Genera un archivo .xlsx nativo. Requiere phpoffice/phpspreadsheet.

use hqsoft\reportkit\renderers\spreadsheet\SpreadsheetRenderer;

$renderer = new SpreadsheetRenderer();
$content = $renderer->render($doc); // Retorna el contenido binario del archivo
file_put_contents('reporte.xlsx', $content);

CSV

Exportación rápida a formato CSV.

use hqsoft\reportkit\renderers\csv\CsvRenderer;

$renderer = new CsvRenderer();
echo $renderer->render($doc);

Word / DOCX

Genera un archivo .docx básico sin depender de una librería adicional.

use hqsoft\reportkit\renderers\docx\DocxRenderer;

$renderer = new DocxRenderer();
$content = $renderer->render($doc);
file_put_contents('reporte.docx', $content);

Estilos (CellStyle)

Puedes aplicar estilos detallados a tus celdas usando la clase CellStyle.

use hqsoft\reportkit\document\CellStyle;

$estiloResaltado = CellStyle::create()
    ->bold()
    ->background('#FFFF00')
    ->color('#FF0000')
    ->align('center')
    ->border('bottom', 'thin', '#000000');

$doc->row(function($row) use ($estiloResaltado) {
    $row->col(12)->text('¡Importante!')->style($estiloResaltado);
});

Capacidades de Estilo

• Texto: bold(), italic(), decoration('underline'), decoration('line-through')
• Fuente: fontFamily('Arial'), fontSize(14)
• Color: color('#333'), background('#f0f0f0')
• Alineación: align('center'), valign('middle')
• Bordes: border('all', 'thin', '#000')
• Espaciado: padding(10) (se convierte a indentación en Excel)
• Dimensiones: width(200) (ancho de columna), height(50) (alto de fila)

Formatos de Datos

Puedes especificar el tipo de dato de una columna para asegurar que se formatee correctamente en Excel y HTML (ej. moneda, fechas).

use hqsoft\reportkit\document\Column;

$doc->row(function($row) {
    // Moneda
    $row->col(6)->text('12500.50')->format(Column::FORMAT_CURRENCY);
    
    // Porcentaje
    $row->col(6)->text('0.15')->format(Column::FORMAT_PERCENTAGE);
    
    // Fecha (entrada YYYY-MM-DD -> salida DD/MM/YYYY)
    $row->col(6)->text('2026-02-03')->format(Column::FORMAT_DATE);
    
    // Número con separadores
    $row->col(6)->text('1000000')->format(Column::FORMAT_NUMBER);
});

Estilos Nombrados

Para evitar repetir definiciones, puedes registrar estilos en el documento:

$doc->addStyle('titulo', CellStyle::create()->fontSize(20)->bold());

// Usar por nombre
$doc->row(function($row) {
    $row->col(24)->text('Mi Título')->style('titulo');
});

Plantillas dinámicas

ReportKit ahora incluye una capa de plantillas híbridas bajo hqsoft\reportkit\template. Su objetivo es expandir una plantilla PHP a un Document neutral antes de renderizar.

Capacidades de esta primera versión:

• placeholders con sintaxis {{ruta.valor}}
• texto mixto dentro de una misma celda
• loops de bloques estructurados
• reutilización de estilos, formatos, imágenes y layout actuales

Ejemplo básico:

use hqsoft\reportkit\document\Column;
use hqsoft\reportkit\template\TemplateDocument;

$template = TemplateDocument::create();

$template->row(function($row) {
    $row->col(24)->text('Comparece {{cliente.nombre}} con domicilio en {{cliente.direccion}}.');
});

$template->loop('conceptos', function($section) {
    $section->row(function($row) {
        $row->col(18)->text('{{descripcion}}');
        $row->col(6)->format(Column::FORMAT_CURRENCY)->text('{{monto}}');
    });
});

$doc = $template->expand([
    'cliente' => [
        'nombre' => 'María Pérez',
        'direccion' => 'Av. Reforma 123',
    ],
    'conceptos' => [
        ['descripcion' => 'Honorarios', 'monto' => '1500'],
        ['descripcion' => 'Gastos', 'monto' => '300'],
    ],
]);

Notas de diseño:

• Los loops repiten bloques completos, no fragmentos arbitrarios de texto.
• Si una variable no existe, se reemplaza por cadena vacía.
• Si un loop no encuentra una colección iterable, el bloque se omite.
• La salida oficial de la plantilla siempre es un Document.