HTML para PDF fiel ao navegador, sem navegador no servidor. O navegador de quem exporta calcula o layout; o PHP só desenha o PDF. Funciona em hospedagem compartilhada (PHP + GD).

Visão geral

Gerar PDF a partir de HTML costuma cair num destes becos:

O Jh2Pdf parte de outra ideia: o navegador de quem exporta já é o melhor motor de layout que existe, e já está aberto. Em vez de reimplementar CSS no PHP, o navegador calcula onde fica cada palavra, caixa, borda e imagem, e o PHP só desenha essas posições. Não há quebra de linha nem cálculo de layout no servidor para errar.

Como funciona

 NAVEGADOR (js/jh2pdf.js)                               SERVIDOR (PHP)
 ────────────────────────                               ──────────────
 seu HTML + seu CSS                                     Options  (tempDir, fontDir, imageResolver…)
   │ desenha cada página fora da tela                      │
   │ (espera fontes e imagens)                             ▼
   ▼                                                    Layout::clean()   valida tudo (o JSON é hostil)
 extractLayout()  percorre o DOM:                          │
   getComputedStyle + Range.getClientRects por palavra     ▼
   │                                                    Renderer::render()  → Dompdf\Cpdf
   ▼                                                       R retângulo · B bordas · T texto · I imagem
 JSON de operações ──────── POST ────────────────────►     M marca à mão · L linha · C/E recorte
 { w, h, pages: [{ bg, ops: [...] }] }                     │
                                                           ▼
                                                        bytes do PDF

1. Medição (navegador). Cada página é inserida num contêiner fora da tela, dentro do seu próprio documento, então o seu CSS vale. O módulo espera as fontes (document.fonts.ready) e as imagens (até 4 s cada).
2. Extração. Para cada elemento visível, lê o estilo calculado e as caixas; para cada palavra, a posição e a largura exatas. O resultado é uma lista ordenada de operações de desenho (a ordem é a ordem de pintura).
3. Desenho (servidor). O PHP valida o JSON e desenha as operações com o Cpdf do Dompdf, usado só como "canvas" de PDF. Cada palavra é posicionada na linha de base e tem o espaçamento entre letras ajustado para ter exatamente a largura medida.

Requisitos

Instalação

Com o Composer

composer require geisonq/jh2pdf

Ou, a partir deste repositório: composer install na raiz (instala o Dompdf em vendor/).

Sem o Composer

Copie a pasta e use o autoloader incluído. O Dompdf continua necessário e precisa ser carregado por você:

require '/caminho/jh2pdf/autoload.php';      // classes Jh2Pdf\*
require '/caminho/vendor/autoload.php';      // Dompdf

No navegador

Copie js/jh2pdf.js para o seu site. É um módulo ES sem dependências (~30 KB, sem minificar).

Início rápido

1. Navegador

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

const layout = await extractLayout(
  ['<h1>Olá</h1><p>Primeira página</p>', '<p>Segunda página</p>'],  // um fragmento de HTML por página
  { width: 794, height: 1123 }                                       // A4 retrato em 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);   // limite o corpo
$layout = json_decode((string)$raw, true);
if (!is_array($layout)) { http_response_code(400); exit; }

$options = new Jh2Pdf\Options('/caminho/gravavel');
try {
    $pdf = (new Jh2Pdf\Renderer($options))->render($layout, 'Título do documento');
} catch (Jh2Pdf\Exception $e) {
    error_log((string)$e->getPrevious());             // o detalhe fica na exceção anterior
    http_response_code(500); exit;
}
header('Content-Type: application/pdf');
echo $pdf;

Exemplos executáveis: examples/minimal/ (o mínimo) e demo/ (galeria com tabelas, efeitos e imagens).

API JavaScript

extractLayout(pages, options) → Promise<Layout>

pages é um array com uma entrada por página: uma string de HTML, um objeto { html } ou qualquer valor, se você passar wrap.

Retorna { w, h, pages: [{ bg, ops }] }, pronto para JSON.stringify. Lança Error se faltar width ou height.

API PHP

Namespace Jh2Pdf, PHP 8.1 com strict_types.

Options

Formato do JSON

É o contrato entre o JS e o PHP. Medidas em px CSS, origem no canto superior esquerdo, cores #rrggbb, opacidade de 0 a 1. A referência completa está em docs/format.md.

{ "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 suportado

O layout em si (flexbox, grid, posicionamento, calc(), variáveis, unidades) é sempre suportado, porque quem calcula é o navegador. A tabela abaixo trata do que é desenhado.

Páginas e tamanhos

Cada item de pages é uma página do PDF, do tamanho de width × height. Não há paginação automática: o que passar da altura da página é cortado. Divida o conteúdo em páginas antes de extrair (por exemplo, uma seção por página, ou medindo alturas no navegador).

O tamanho aceito vai de 200 a 4000 px por lado.

Fontes

Para o PDF sair igual à tela, o navegador e o servidor precisam usar os mesmos arquivos de fonte. O Dompdf não lê woff2 nem fontes variáveis, então o servidor usa TTF estáticos, um por peso. Há três jeitos de dar fontes a ele:

$options = new Jh2Pdf\Options('/caminho/gravavel');
$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('/mais/fontes');

Como a fonte é escolhida

As mesmas regras do CSS:

• Família: a primeira família da lista font-family que o servidor tem ('Roboto', Arial, sans-serif usa Roboto, ou Arial se você a tiver; nomes genéricos como sans-serif não são fontes). O navegador envia até 5 reservas depois da primeira.
• Estilo: itálico, se a família tem arquivo itálico; senão, o estilo normal inclinado em 12°, como o navegador faz.
• Peso: de 100 a 900, o arquivo mais próximo que você tiver: pedir 800 com só 400 e 700 usa o 700; 300 usa o 400.

Faça o navegador usar os mesmos arquivos

Gere o CSS @font-face a partir das mesmas fontes, para nunca haver duas listas para manter iguais:

// uma vez, ao publicar (ler os nomes dentro dos TTF é lento demais para fazer a cada requisição)
file_put_contents('public/fonts.css', Jh2Pdf\FontFaces::css($options, '/fonts/'));

ou pela linha de comando: php tools/fonts-css.php --dir fonts --url /fonts/ --out public/fonts.css Instalado pelo Composer, o script fica em vendor/geisonq/jh2pdf/tools/fonts-css.php.

Nunca falhe em silêncio

Uma família que o servidor não tem sai na fallbackFont (DejaVu Sans), e o PDF fica diferente da tela. Para pegar isso:

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

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

A checagem acontece antes de desenhar qualquer coisa. Use strictFonts em desenvolvimento e nos testes; em produção, registre no log com onMissingFont ou missingFonts().

Adicionar uma fonte a partir de uma fonte variável

pip install fonttools brotli
python tools/generate-fonts.py --fonts fonts.json --src pasta-das-fontes --out fonts

Python só é necessário para gerar os arquivos (--weights 300,400,700 escolhe os pesos; o formato do fonts.json está no cabeçalho do script). Ele grava a família, o estilo e o peso certos dentro de cada TTF. Para corrigir os nomes de TTF estáticos que você já tem: python tools/generate-fonts.py --fix-names pasta. O servidor usa os TTF prontos. Confira se a licença da fonte permite embuti-la em PDF.

Incluídas (12 famílias, SIL OFL 1.1): Barlow Condensed, DM Sans, Fira Code, Inter, JetBrains Mono, Montserrat, Nunito, Open Sans e quatro serifadas renomeadas: Jh Serif (da Lora), Jh Serif Text (da Merriweather), Jh Display (da Playfair Display) e Jh Serif Book (da Source Serif 4). Têm itálico: DM Sans e Jh Serif.

Imagens

O src de cada imagem vem do navegador e não é confiável. Por padrão só data: é aceito (nada de disco nem de rede). Para servir imagens do seu sistema, implemente um resolvedor e valide se aquele usuário pode ver aquele arquivo:

final class MeuResolver implements Jh2Pdf\ImageResolver
{
    public function load(string $src): ?string
    {
        // só o seu padrão de URL; nunca concatene o src num caminho
        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 MeuResolver();

No navegador, acceptImage evita enviar o que o servidor recusaria. As imagens são reduzidas ao tamanho em que aparecem (~150 dpi): sem transparência viram JPEG, com transparência continuam PNG.

Marcas à mão

Extensão opcional, desligada por padrão (não é HTML/CSS padrão), para destacar trechos com um traço "feito à mão": underline, circle, highlight, box, strike, cross.

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

Com marks: true, o extrator envia a caixa do trecho e a cor; o PHP desenha o SVG da forma, que está em resources/marks.css (ou no seu CSS, via Options::$marksCss). Sem --mk-color, usa a cor do texto. Os elementos pares usam a 2ª variação (:nth-of-type(even)), e uma marca com display: inline que quebra de linha ganha um desenho por linha. Sem marks: true, as classes .mk são tratadas como qualquer outro elemento. O CSS de tela (máscara no ::after) está em demo/pages.css.

Segurança

Há duas fronteiras, e em cada uma o que vem do outro lado é tratado como hostil.

Servidor: o JSON do navegador

Qualquer pessoa que consiga chamar o seu endpoint pode mandar um JSON feito à mão. Por desenho, o servidor nunca interpreta HTML, CSS ou JavaScript.

Navegador: o HTML de entrada

O HTML de cada página entra no DOM de quem está exportando. Se ele vier de outra pessoa, é uma entrada hostil (XSS). O módulo primeiro coloca o HTML num <template> inerte e remove script, iframe, object, embed, link, meta, base, atributos on*, srcdoc, URLs javascript: e data: que não sejam imagem, e expression(). Isso é um filtro de reserva: para conteúdo de terceiros, use um sanitizador de verdade:

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

<style> e url() no CSS continuam permitidos. Eles não executam código, mas podem disparar requisições (rastreamento).

Desempenho

Medido com a galeria de exemplos (7 páginas A4, ~2 400 operações, 9 imagens com filtro) num PC comum com XAMPP e PHP 8.2:

• Os filtros (blur, drop-shadow) são a parte mais cara. Sem eles, páginas de texto e tabelas levam frações de segundo.
• A mesma imagem com o mesmo filtro e tamanho é processada uma vez só por PDF (há cache).
• Para documentos grandes, envie as imagens por URL e use um ImageResolver, em vez de data: repetido no JSON.

Solução de problemas

Dependências

Em produção

No navegador: nenhuma dependência (js/jh2pdf.js é JavaScript puro).

Só em desenvolvimento

Licença

O código do Jh2Pdf está sob a licença MIT, © 2026 Geison Quevedo. Qualquer pessoa pode usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e vender, inclusive em projetos fechados, desde que mantenha o aviso de copyright e o texto da licença. As fontes (OFL) e o Dompdf (LGPL) têm as licenças próprias, descritas em Dependências.

Estrutura

jh2pdf/
├── LICENSE               MIT
├── README.md             resumo e início rápido
├── composer.json         pacote (autoload PSR-4: Jh2Pdf\ → src/)
├── autoload.php          autoloader para quem não usa o Composer
├── src/                  PHP: Renderer, Options, Layout, ImageResolver, DataUriImageResolver,
│                              Images, ImageFilter, Fonts, Marks, Svg, Exception
├── js/jh2pdf.js          extrator de layout (módulo ES, sem dependências)
├── fonts/                TTF estáticos (OFL) + OFL.txt
├── resources/marks.css   desenhos SVG das marcas à mão
├── docs/                 esta documentação (en, pt-BR, es) + format.md (o formato do JSON)
├── demo/                 galeria de exemplos (index.html, pages.css, fonts.css, pdf.php)
├── examples/minimal/     o menor exemplo completo
├── tests/run.php         testes (php tests/run.php ou composer test)
├── tools/fonts-css.php   gera o CSS @font-face do navegador a partir das mesmas fontes
└── tools/generate-fonts.py   gera os TTF a partir de fontes variáveis

Contribuindo

• Testes: composer install e composer test. Não há framework de testes, só tests/run.php.
• Critério de qualidade: ficar igual à tela. Gere o PDF pelo navegador (Imprimir → Salvar como PDF) e por esta biblioteca e compare lado a lado, ampliando (por exemplo, com PyMuPDF: page.get_pixmap(dpi=200)).
• Nova operação (por exemplo, degradê radial): (1) o extrator em js/jh2pdf.js passa a emitir a operação; (2) Layout::OPS ganha a letra; (3) Renderer::render ganha o case; (4) documente em docs/format.md; (5) teste em tests/run.php. Valide todo campo novo: é entrada hostil.
• Estilo: PHP 8.1 com declare(strict_types=1), sem dependências além do Dompdf. JS sem dependências, com nomes de topo prefixados com pl.
• Contribuições são aceitas sob a mesma licença do projeto (MIT).