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. A solução é um layout de impressão próprio, que gera PDFs a partir de conteúdos de página TYPO3 independentemente da representação do navegador. O dreipc_pdf não está publicado nem no TER, nem no Packagist, nem no GitHub; por isso, suas funções não podem ser verificadas. As seções a seguir descrevem a abordagem que uma solução desse tipo segue no TYPO3.

Ao contrário do EXT:web2pdf, que converte a página HTML renderizada em PDF com a biblioteca PHP mPDF, uma abordagem orientada a dados trabalha com templates próprios: ela renderiza os elementos de conteúdo de uma página TYPO3 via templates PDF 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. Uma solução de PDF orientada a dados 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. A solução de 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

Uma solução desse tipo utiliza uma biblioteca PHP de PDF como mPDF ou TCPDF para a geração e registra no TYPO3 um tipo de página próprio. 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 soluçã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

O dreipc_pdf não está publicado nem no TER, nem no Packagist, nem no GitHub. Por isso, não é possível verificar quais versões do TYPO3 a extensão suporta, e uma atualização para as versões atuais não está disponível publicamente.

As alternativas para TYPO3 v12/v13: EXT:web2pdf (converte a página HTML com mPDF, 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 uma extensão de PDF existente para uma solução customizada pode aproveitar os templates Fluid para PDF que já existem, 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.