HTML a PDF idéntico al navegador, sin navegador en el servidor. El navegador de quien exporta calcula el diseño; PHP solo dibuja el PDF. Funciona en hosting compartido (PHP + GD).

Visión general

Generar PDF a partir de HTML suele terminar en uno de estos callejones sin salida:

Jh2Pdf parte de otra idea: el navegador de quien exporta ya es el mejor motor de diseño que existe, y ya está abierto. En lugar de reimplementar CSS en PHP, el navegador calcula dónde va cada palabra, caja, borde e imagen, y PHP solo dibuja esas posiciones. No hay saltos de línea ni cálculo de diseño en el servidor que puedan fallar.

Cómo funciona

 NAVEGADOR (js/jh2pdf.js)                               SERVIDOR (PHP)
 ────────────────────────                               ──────────────
 tu HTML + tu CSS                                       Options  (tempDir, fontDir, imageResolver…)
   │ dibuja cada página fuera de la pantalla               │
   │ (espera fuentes e imágenes)                           ▼
   ▼                                                    Layout::clean()   valida todo (el JSON es hostil)
 extractLayout()  recorre el DOM:                          │
   getComputedStyle + Range.getClientRects por palabra     ▼
   │                                                    Renderer::render()  → Dompdf\Cpdf
   ▼                                                       R rectángulo · B bordes · T texto · I imagen
 JSON de operaciones ─────── POST ───────────────────►     M marca a mano · L línea · C/E recorte
 { w, h, pages: [{ bg, ops: [...] }] }                     │
                                                           ▼
                                                        bytes del PDF

1. Medición (navegador). Cada página se inserta en un contenedor fuera de la pantalla, dentro de tu propio documento, así que tu CSS se aplica. El módulo espera las fuentes (document.fonts.ready) y las imágenes (hasta 4 s cada una).
2. Extracción. Para cada elemento visible lee el estilo calculado y las cajas; para cada palabra, la posición y el ancho exactos. El resultado es una lista ordenada de operaciones de dibujo (el orden es el orden de pintado).
3. Dibujo (servidor). PHP valida el JSON y dibuja las operaciones con el Cpdf de Dompdf, usado solo como "lienzo" de PDF. Cada palabra se coloca en su línea base y su espaciado entre letras se ajusta para tener exactamente el ancho medido.

Requisitos

Instalación

Con Composer

composer require geisonq/jh2pdf

O, desde este repositorio: composer install en la raíz (instala Dompdf en vendor/).

Sin Composer

Copia la carpeta y usa el autoloader incluido. Dompdf sigue siendo necesario y tienes que cargarlo tú:

require '/ruta/jh2pdf/autoload.php';      // clases Jh2Pdf\*
require '/ruta/vendor/autoload.php';      // Dompdf

En el navegador

Copia js/jh2pdf.js a tu sitio. Es un módulo ES sin dependencias (~30 KB, sin minificar).

Inicio rápido

1. Navegador

import { extractLayout } from './jh2pdf.js';

const layout = await extractLayout(
  ['<h1>Hola</h1><p>Primera página</p>', '<p>Segunda página</p>'],  // un fragmento de HTML por página
  { width: 794, height: 1123 }                                       // A4 vertical en px CSS
);
const res = await fetch('/pdf.php', {
  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(layout),
});
const pdf = await res.blob();                                  // application/pdf
window.open(URL.createObjectURL(pdf));

2. Servidor (pdf.php)

require 'vendor/autoload.php';

$raw    = file_get_contents('php://input', false, null, 0, 5_000_000);   // limita el cuerpo
$layout = json_decode((string)$raw, true);
if (!is_array($layout)) { http_response_code(400); exit; }

$options = new Jh2Pdf\Options('/ruta/con/escritura');
try {
    $pdf = (new Jh2Pdf\Renderer($options))->render($layout, 'Título del documento');
} catch (Jh2Pdf\Exception $e) {
    error_log((string)$e->getPrevious());             // el detalle está en la excepción anterior
    http_response_code(500); exit;
}
header('Content-Type: application/pdf');
echo $pdf;

Ejemplos ejecutables: examples/minimal/ (lo mínimo) y demo/ (galería con tablas, efectos e imágenes).

API JavaScript

extractLayout(pages, options) → Promise<Layout>

pages es un array con una entrada por página: un string de HTML, un objeto { html } o cualquier valor, si pasas wrap.

Devuelve { w, h, pages: [{ bg, ops }] }, listo para JSON.stringify. Lanza Error si falta width o height.

API PHP

Namespace Jh2Pdf, PHP 8.1 con strict_types.

Options

Formato del JSON

Es el contrato entre el JS y el PHP. Medidas en px CSS, origen en la esquina superior izquierda, colores #rrggbb, opacidad de 0 a 1. La referencia completa está en docs/format.md (en portugués).

{ "w": 794, "h": 1123,
  "pages": [ { "bg": "#ffffff", "ops": [
      { "t": "R", "x": 0, "y": 0, "w": 794, "h": 300, "c": "#4f46e5", "a": 1, "r": [12,12,0,0] },
      { "t": "T", "x": 60, "y": 80, "w": 92.4, "h": 44, "s": "Lorem", "f": "Jh Display", "g": 700, "z": 40, "c": "#ffffff" }
  ] } ] }

CSS soportado

El diseño en sí (flexbox, grid, posicionamiento, calc(), variables, unidades) siempre está soportado, porque quien lo calcula es el navegador. La tabla de abajo trata de lo que se dibuja.

Páginas y tamaños

Cada elemento de pages es una página del PDF, del tamaño width × height. No hay paginación automática: lo que exceda la altura de la página se corta. Divide el contenido en páginas antes de extraer (por ejemplo, una sección por página, o midiendo alturas en el navegador).

El tamaño aceptado va de 200 a 4000 px por lado.

Fuentes

Para que el PDF salga igual que la pantalla, el navegador y el servidor deben usar los mismos archivos de fuente. Dompdf no lee woff2 ni fuentes variables, así que el servidor usa TTF estáticos, uno por peso. Hay tres formas de dárselas:

$options = new Jh2Pdf\Options('/ruta/con/escritura');
$options->addFont('Roboto', 400, '/fonts/Roboto-Regular.ttf')
        ->addFont('Roboto', 400, '/fonts/Roboto-Italic.ttf', italic: true)
        ->addFont('Roboto', 700, '/fonts/Roboto-Bold.ttf')
        ->addFontDir('/mas/fuentes');

Cómo se elige la fuente

Las mismas reglas que CSS:

• Familia: la primera familia de la lista font-family que el servidor tiene ('Roboto', Arial, sans-serif usa Roboto, o Arial si la tienes; los nombres genéricos como sans-serif no son fuentes). El navegador envía hasta 5 de reserva después de la primera.
• Estilo: cursiva si la familia tiene archivo en cursiva; si no, el estilo normal inclinado 12°, como hace el navegador.
• Peso: de 100 a 900, el archivo más cercano que tengas: pedir 800 con solo 400 y 700 usa el 700; 300 usa el 400.

Haz que el navegador use los mismos archivos

Genera el CSS @font-face a partir de las mismas fuentes, para no tener nunca dos listas que mantener iguales:

// una vez, al publicar (leer los nombres dentro de los TTF es demasiado lento para hacerlo en cada petición)
file_put_contents('public/fonts.css', Jh2Pdf\FontFaces::css($options, '/fonts/'));

o desde la línea de comandos: php tools/fonts-css.php --dir fonts --url /fonts/ --out public/fonts.css Instalado con Composer, el script está en vendor/geisonq/jh2pdf/tools/fonts-css.php.

Nunca falles en silencio

Una familia que el servidor no tiene se dibuja con fallbackFont (DejaVu Sans), y el PDF queda distinto de la pantalla. Para detectarlo:

$options->strictFonts = true;   // lanza Jh2Pdf\Exception: "Missing fonts: Roboto 400, Roboto 700 italic."
$options->onMissingFont = fn(string $family, int $weight, bool $italic) => error_log("Fuente faltante: $family $weight");

$pdf = $renderer->render($layout);
$renderer->missingFonts();      // [['family' => 'Roboto', 'weight' => 400, 'italic' => false], …]

La comprobación se hace antes de dibujar nada. Usa strictFonts en desarrollo y en las pruebas; en producción, registra con onMissingFont o missingFonts().

Agregar una fuente a partir de una fuente variable

pip install fonttools brotli
python tools/generate-fonts.py --fonts fonts.json --src carpeta-de-fuentes --out fonts

Python solo se necesita para generar los archivos (--weights 300,400,700 elige los pesos; el formato de fonts.json está en la cabecera del script). Escribe la familia, el estilo y el peso correctos dentro de cada TTF. Para corregir los nombres de TTF estáticos que ya tienes: python tools/generate-fonts.py --fix-names carpeta. El servidor usa los TTF ya listos. Comprueba que la licencia de la fuente permita incrustarla en PDF.

Incluidas (12 familias, SIL OFL 1.1): Barlow Condensed, DM Sans, Fira Code, Inter, JetBrains Mono, Montserrat, Nunito, Open Sans y cuatro serif renombradas: Jh Serif (de Lora), Jh Serif Text (de Merriweather), Jh Display (de Playfair Display) y Jh Serif Book (de Source Serif 4). Con cursiva: DM Sans y Jh Serif.

Imágenes

El src de cada imagen viene del navegador y no es confiable. Por defecto solo se acepta data: (nada de disco ni de red). Para servir imágenes de tu sistema, implementa un resolvedor y verifica que ese usuario pueda ver ese archivo:

final class MiResolvedor implements Jh2Pdf\ImageResolver
{
    public function load(string $src): ?string
    {
        // solo tu patrón de URL; nunca concatenes el src en una ruta
        if (!preg_match('~^/uploads/([a-f0-9]{16}\.(png|jpg))$~', $src, $m)) return null;
        $f = '/var/app/uploads/' . $m[1];
        return is_file($f) ? file_get_contents($f) : null;
    }
}
$options->imageResolver = new MiResolvedor();

En el navegador, acceptImage evita enviar lo que el servidor rechazaría. Las imágenes se reducen al tamaño en que se muestran (~150 dpi): sin transparencia pasan a JPEG, con transparencia siguen siendo PNG.

Marcas a mano

Extensión opcional, desactivada por defecto (no es HTML/CSS estándar), para resaltar texto con un trazo "hecho a mano": underline, circle, highlight, box, strike, cross.

<span class="mk mk-circle" style="--mk-color:#e5484d">importante</span>

Con marks: true, el extractor envía la caja y el color del texto marcado; PHP dibuja el SVG de la forma, que está en resources/marks.css (o en tu propio CSS, mediante Options::$marksCss). Sin --mk-color, se usa el color del texto. Los elementos pares usan la 2.ª variante (:nth-of-type(even)), y una marca con display: inline que se parte en varias líneas recibe un dibujo por línea. Sin marks: true, las clases .mk se tratan como cualquier otro elemento. El CSS de pantalla (una máscara en ::after) está en demo/pages.css.

Seguridad

Hay dos fronteras, y en cada una lo que viene del otro lado se trata como hostil.

Servidor: el JSON del navegador

Cualquiera que pueda llamar a tu endpoint puede enviar un JSON hecho a mano. Por diseño, el servidor nunca interpreta HTML, CSS ni JavaScript.

Navegador: el HTML de entrada

El HTML de cada página entra en el DOM de quien exporta. Si viene de otra persona, es una entrada hostil (XSS). El módulo primero coloca el HTML en un <template> inerte y elimina script, iframe, object, embed, link, meta, base, atributos on*, srcdoc, URLs javascript: y data: que no sean imagen, y expression(). Esto es un filtro de respaldo: para contenido de terceros, usa un sanitizador de verdad:

extractLayout(pages, { width, height, sanitize: (h) => DOMPurify.sanitize(h) });

<style> y url() en el CSS siguen permitidos. No ejecutan código, pero pueden disparar peticiones (rastreo).

Rendimiento

Medido con la galería de ejemplos (7 páginas A4, ~2400 operaciones, 9 imágenes con filtro) en un PC común con XAMPP y PHP 8.2:

• Los filtros (blur, drop-shadow) son la parte más costosa. Sin ellos, las páginas de texto y tablas tardan fracciones de segundo.
• La misma imagen con el mismo filtro y tamaño se procesa una sola vez por PDF (hay caché).
• Para documentos grandes, envía las imágenes por URL y usa un ImageResolver, en lugar de repetir data: en el JSON.

Solución de problemas

Dependencias

En producción

En el navegador: ninguna dependencia (js/jh2pdf.js es JavaScript puro).

Solo en desarrollo

Licencia

El código de Jh2Pdf está bajo la licencia MIT, © 2026 Geison Quevedo. Cualquier persona puede usarlo, copiarlo, modificarlo, fusionarlo, publicarlo, distribuirlo, sublicenciarlo y venderlo, incluso en proyectos cerrados, siempre que mantenga el aviso de copyright y el texto de la licencia. Las fuentes (OFL) y Dompdf (LGPL) tienen sus propias licencias, descritas en Dependencias.

Estructura

jh2pdf/
├── LICENSE               MIT
├── README.md             resumen e inicio rápido
├── composer.json         paquete (autoload PSR-4: Jh2Pdf\ → src/)
├── autoload.php          autoloader para quien no usa Composer
├── src/                  PHP: Renderer, Options, Layout, ImageResolver, DataUriImageResolver,
│                              Images, ImageFilter, Fonts, Marks, Svg, Exception
├── js/jh2pdf.js          extractor de diseño (módulo ES, sin dependencias)
├── fonts/                TTF estáticos (OFL) + OFL.txt
├── resources/marks.css   dibujos SVG de las marcas a mano
├── docs/                 esta documentación (en, pt-BR, es) + format.md (el formato del JSON)
├── demo/                 galería de ejemplos (index.html, pages.css, fonts.css, pdf.php)
├── examples/minimal/     el ejemplo completo más pequeño
├── tests/run.php         pruebas (php tests/run.php o composer test)
├── tools/fonts-css.php   genera el CSS @font-face del navegador a partir de las mismas fuentes
└── tools/generate-fonts.py   genera los TTF a partir de fuentes variables

Cómo contribuir

• Pruebas: composer install y composer test. No hay framework de pruebas, solo tests/run.php.
• Criterio de calidad: quedar igual que la pantalla. Genera el PDF desde el navegador (Imprimir → Guardar como PDF) y con esta biblioteca y compáralos lado a lado, ampliando (por ejemplo, con PyMuPDF: page.get_pixmap(dpi=200)).
• Nueva operación (por ejemplo, degradado radial): (1) el extractor en js/jh2pdf.js emite la operación; (2) Layout::OPS recibe la letra; (3) Renderer::render recibe el case; (4) documéntala en docs/format.md; (5) pruébala en tests/run.php. Valida cada campo nuevo: es una entrada hostil.
• Estilo: PHP 8.1 con declare(strict_types=1), sin dependencias aparte de Dompdf. JS sin dependencias, con nombres de nivel superior con el prefijo pl.
• Las contribuciones se aceptan bajo la misma licencia del proyecto (MIT).