fluid_fpdf para TYPO3

Quando PDFs surgem de dados em vez de screenshots, é necessário fluid_fpdf

Existem duas abordagens fundamentalmente diferentes para gerar PDFs no TYPO3. A abordagem screenshot (web2pdf): a página web renderizada é capturada como imagem e empacotada em PDF. Simples, mas o resultado parece uma página web impressa, com navegação, footer e artefatos responsivos. A abordagem orientada a dados (fluid_fpdf): um template Fluid define o layout do PDF, dados TYPO3 preenchem os placeholders, o resultado é um documento limpo com design corporativo. Faturas, certificados, propostas, relatórios - tudo que precisa existir como documento precisa da abordagem orientada a dados.

fluid_fpdf usa a biblioteca FPDF (uma classe PHP enxuta para geração de PDF) e a conecta com o motor de templates Fluid do TYPO3. O resultado: desenvolvedores escrevem layouts PDF na mesma linguagem de template que usam para templates HTML.

Cenários típicos de uso

Geração automatizada de faturas. Uma loja online ou sistema de reservas no TYPO3 gera uma fatura a cada pedido. Os dados da fatura (itens, preços, dados do cliente, impostos) vêm do banco de dados, o layout de um template Fluid. Em um organizador de eventos, fluid_fpdf gera 200 a 300 faturas por mês sem intervenção manual. Cada fatura carrega número da fatura, logo da empresa, dados bancários e informações obrigatórias legais.

Certificados de participação e confirmações. Instituições educacionais, associações e empresas emitem certificados após treinamentos, workshops ou provas. O nome do participante, a data, o nome do curso e a assinatura do instrutor são automaticamente extraídos dos dados TYPO3. Em uma instituição educacional com 5.000 participantes por ano, a automatização economiza aproximadamente 250 horas de trabalho que antes eram gastas na criação manual de PDF no InDesign.

Propostas e exposés. Corretores de imóveis, consultorias e agências criam propostas com conteúdos variáveis: dados do cliente, serviços selecionados, preços individuais. O layout PDF é fixo (design corporativo), os conteúdos variam. fluid_fpdf preenche o template com os dados de um formulário TYPO3 ou módulo backend.

Arquitetura técnica

fluid_fpdf conecta dois sistemas: o motor de templates Fluid do TYPO3 e a biblioteca FPDF. A arquitetura trabalha em três passos.

Primeiro: o template Fluid define a estrutura do PDF. Em vez de tags HTML, o template usa ViewHelpers especiais para elementos PDF: <fpdf:page> para uma nova página, <fpdf:cell> para uma célula de texto, <fpdf:image> para uma imagem, <fpdf:line> para uma linha. A sintaxe é Fluid, a saída não é HTML, mas comandos FPDF.

Segundo: TYPO3 fornece os dados. Via controller ou DataProcessor, os dados necessários (itens de fatura, dados de cliente, informações de produto) são passados ao template. Funciona identicamente ao tratamento de dados em templates Fluid HTML: {invoice.items}, {customer.name}, {order.total}.

Terceiro: FPDF renderiza o PDF. Os ViewHelpers traduzem a lógica Fluid em chamadas de método FPDF (SetFont, Cell, Image, Ln). FPDF gera o PDF como arquivo binário que é enviado diretamente ao navegador (download) ou armazenado no sistema de arquivos (p.ex. para envio por e-mail).

O suporte a fontes é um detalhe importante: FPDF suporta por padrão apenas 14 fontes (Helvetica, Times, Courier e variantes). Para fontes corporativas, arquivos TTF devem ser convertidos como arquivos de fonte FPDF. A ferramenta MakeFont do FPDF cuida da conversão.

Problemas frequentes e soluções

Caracteres UTF-8 não são exibidos corretamente. FPDF trabalha internamente com codificação Latin-1. Acentos (ã, ç, é, ê, í, ó, ú, à), caracteres poloneses (ą, ę, ł) ou letras cirílicas requerem suporte UTF-8. Solução: usar tFPDF (uma variante FPDF com suporte UTF-8) em vez de FPDF. fluid_fpdf suporta tFPDF como backend. Alternativamente: usar mPDF, que suporta UTF-8 nativamente.

Quebras de página em conteúdos dinâmicos. Uma fatura com 5 itens cabe em uma página, uma com 50 itens precisa de 3 páginas. FPDF não quebra páginas automaticamente quando o conteúdo excede a margem da página. Solução: verificar a altura restante da página antes de cada item (GetY() + altura da linha > final da página) e inserir uma nova página quando necessário. Cabeçalhos e rodapés são repetidos automaticamente em cada página via métodos Header()/Footer().

Desenvolvimento de layout é trabalhoso. Sem preview visual, o desenvolvedor precisa gerar o PDF após cada alteração para ver o resultado. Solução: configurar uma rota de preview que exibe o PDF no navegador (modo de saída “Inline” em vez de “Download”). A cada refresh, o PDF é regenerado. Isso acelera consideravelmente o ciclo de desenvolvimento.

Migração e compatibilidade de versões

fluid_fpdf suporta TYPO3 v10 e v11. Para v12 não existe versão oficial, o esforço de portabilidade é moderado (ajustes Extbase, registro de ViewHelper).

As alternativas para TYPO3 v12/v13: EXT:pdfviewhelpers (usa TCPDF em vez de FPDF, mais funcionalidades, manutenção ativa, compatível com v12), uma solução customizada com mPDF como pacote Composer (HTML/CSS como entrada, layout mais simples que com FPDF) ou uma solução headless com serviço PDF externo (Gotenberg, wkhtmltopdf como container Docker).

A migração de fluid_fpdf para EXT:pdfviewhelpers é gerenciável: a estrutura de templates é similar (baseada em ViewHelper), mas os nomes e parâmetros dos ViewHelpers diferem. Para um projeto com 5 templates PDF, o esforço de migração é de 2 a 4 dias. A Gosign implementou geração de PDF no TYPO3 com todas as bibliotecas comuns e orienta sobre a solução adequada baseada nos requisitos concretos.