dreipc_pdf para TYPO3

Quando visitantes querem baixar páginas TYPO3 como PDF, o resultado precisa de um layout próprio

Visitantes clicam em “Salvar como PDF” e esperam um documento limpo: design corporativo, logo, números de página, sem overhead de navegação. O que a função de impressão do navegador entrega é o oposto: colunas cortadas, headers e footers supérfluos, imagens ausentes. dreipc_pdf resolve esse problema com uma abordagem de renderização própria: a extensão gera PDFs a partir de conteúdos de página TYPO3 com um layout de impressão dedicado, independente da representação do navegador.

Ao contrário do EXT:web2pdf, que converte a página HTML renderizada como screenshot em PDF, dreipc_pdf trabalha de forma orientada a dados. Ele renderiza os elementos de conteúdo de uma página TYPO3 via templates próprios e gera um PDF formatado a partir deles. Isso permite controle total sobre margens, cabeçalhos e rodapés, tamanhos de fonte e quebras de página.

Cenários típicos de uso

Fichas técnicas de produtos a partir do CMS. Fabricantes de máquinas, empresas químicas e fabricantes de tecnologia médica mantêm dados de produtos no TYPO3. Representantes de vendas precisam desses dados como PDF imprimível para visitas a clientes. dreipc_pdf gera a partir da página de produto TYPO3 um PDF com layout corporativo: logo acima, dados técnicos em tabelas, imagem do produto, dados de contato abaixo. Em um cliente com 400 páginas de produto, os PDFs ficam automaticamente disponíveis via botão em cada página, sem criação manual.

Comunicados de imprensa e relatórios corporativos. Departamentos de comunicação publicam comunicados de imprensa no site e os oferecem simultaneamente como PDF para download. dreipc_pdf gera o PDF ao clicar no botão de download, sempre baseado no conteúdo atual. Sem criação manual de PDF, sem risco de versões de download desatualizadas.

Folhetos informativos de órgãos públicos. Instituições públicas disponibilizam formulários, folhetos e informações como PDF. Os conteúdos são mantidos no TYPO3 e entregues automaticamente como PDF atualizado em caso de alterações. A versão PDF tem um layout oficial com cabeçalho institucional e número de referência.

Arquitetura técnica

dreipc_pdf utiliza uma biblioteca PHP de PDF (tipicamente mPDF ou TCPDF) para a geração. A extensão se registra como Page-Type no TYPO3. Ao acessar uma página com o parâmetro PDF-Type (?type=123), em vez do output HTML, um arquivo PDF é gerado e oferecido para download.

O pipeline de renderização trabalha em três passos. Primeiro, a extensão lê os elementos de conteúdo da página TYPO3 solicitada do banco de dados. Segundo, renderiza cada elemento via um template Fluid dedicado para PDF (não o template web padrão). Terceiro, passa a string HTML renderizada ao mPDF/TCPDF, que gera o PDF com as configurações de página definidas.

Os templates PDF são templates Fluid com HTML/CSS que o mPDF entende. mPDF suporta um subconjunto de CSS2 e CSS3: margens de página (@page), cabeçalhos/rodapés, tabelas, imagens, fontes (fontes TTF incorporáveis) e quebras de página (page-break-before, page-break-after). Flexbox e Grid não são suportados, o trabalho de layout é feito via tabelas ou Float.

A configuração inclui: formato de página (A4, Letter, Custom), orientação (retrato/paisagem), margens, fonte padrão, templates de cabeçalho/rodapé e a atribuição de tipos de elemento de conteúdo a templates PDF. Cada elemento de conteúdo pode ter seu próprio template PDF, diferente da representação web.

Problemas frequentes e soluções

Imagens ausentes no PDF. mPDF carrega imagens via HTTP. Se o servidor está atrás de um reverse proxy ou em ambiente Docker, mPDF pode não conseguir resolver as URLs de imagem próprias. Solução: incorporar imagens pelo caminho local do arquivo em vez da URL. Nos templates Fluid para PDF, usar o caminho absoluto do servidor (/var/www/html/fileadmin/...) em vez do endereço web.

Geração de PDF lenta em páginas complexas. Uma página com 30 elementos de conteúdo e 15 imagens pode levar 5 a 10 segundos para geração do PDF. Com requisições simultâneas, isso sobrecarrega o servidor. Solução: cachear PDFs gerados. Na primeira chamada, o PDF é gerado e armazenado no sistema de arquivos. Chamadas subsequentes entregam a versão cacheada. O cache é invalidado em alterações de conteúdo.

Quebras de página em locais errados. mPDF quebra páginas onde o conteúdo excede a altura da página, mesmo no meio de uma tabela ou parágrafo. Solução: nos templates PDF, definir quebras de página explícitas (<div style="page-break-before: always;">) e proteger tabelas contra quebra com <table style="page-break-inside: avoid;">.

Migração e compatibilidade de versões

dreipc_pdf é uma extensão de nicho com comunidade limitada. A última versão estável suporta TYPO3 v10 e v11. Para v12 não existe atualização oficial, o esforço de portabilidade é moderado (ajustes Extbase, atualizações TCA).

As alternativas para TYPO3 v12/v13: EXT:web2pdf (baseada em screenshot, mais simples, menos controle sobre o layout), EXT:pdfviewhelpers (baseada em ViewHelper, funciona com TCPDF), EXT:fluid_fpdf (templates Fluid com backend FPDF) ou uma solução customizada com mPDF como pacote Composer. A solução customizada tem a vantagem do controle total e independência de extensões de terceiros.

Quem migra de dreipc_pdf para uma solução customizada pode aproveitar os templates Fluid existentes para PDF, desde que usem HTML/CSS compatível com mPDF. O wrapper de renderização deve ser reescrito, mas os templates permanecem. Para um projeto típico com 5 templates PDF, o esforço de migração é de 2 a 3 dias. A Gosign implementou geração de PDF no TYPO3 com diversas bibliotecas e recomenda a solução adequada conforme o requisito.