Guia de Comparação e Implantação

Não sabe quais pacotes você precisa? Use o assistente interativo abaixo, ou navegue pelos cenários de implantação e pela matriz de decisão para encontrar sua configuração ideal.

Encontre Sua Configuração Perfeita

1

Tipo de projeto

2

Versão do PHP

3

Framework

4

HTML para PDF

5

Recursos Pro

Tipo de projeto

Gere Sua Configuração

Gerador de configuração

Selecione seus pacotes e opções para gerar arquivos de configuração prontos para uso.

Pacotes

CoreArtisanProLaravelSymfonyCodeIgniterAdaptation

Core é sempre incluído

Opções do Docker

Imagem base

Fontes CJKInstalar Noto Sans CJK para suporte a chinês, japonês e coreanoRoadRunnerAdicionar RoadRunner para servir HTTP com worker persistente

Código gerado

composer require yeeefang/tcpdf-next

Cenários de Implantação

Diferentes ambientes de hospedagem possuem diferentes capacidades. Veja o que funciona melhor para cada um:

🏠

Hospedagem Compartilhada

Desempenho

Pacotes Recomendados

Core

Acesso PHP limitado, sem shell. Apenas Core com fontes básicas. Sem Chrome/RoadRunner.

🖥

VPS (PHP-FPM)

Desempenho

Pacotes Recomendados

Core Artisan Laravel

Controle total do servidor. Instalar Chrome para HTML→PDF. Adequado para a maioria dos apps.

🖥

VPS + RoadRunner

RoadRunner

Desempenho

Pacotes Recomendados

Core Artisan Laravel

Worker persistente elimina cold starts. Throughput 3-7x maior.

⚙

Servidor Dedicado

Desempenho

Pacotes Recomendados

Core Artisan Pro Laravel

Recursos completos. Ideal para recursos Pro (PAdES, PDF/A-4, HSM).

⚙

Dedicado + RoadRunner

RoadRunner

Desempenho

Pacotes Recomendados

Core Artisan Pro Laravel

Throughput máximo. 9,000+ docs/s com 4 workers.

☸

Kubernetes / Docker

RoadRunner

Desempenho

Pacotes Recomendados

Core Artisan Pro Symfony

Escalonamento horizontal. RoadRunner como processo worker. Nível produção.

Performance: PHP-FPM Padrão vs RoadRunner

O RoadRunner mantém sua aplicação PHP em memória como um worker persistente, eliminando cold starts e aumentando drasticamente o throughput.

PHP-FPM padrão vs RoadRunner

▲ Maior é melhor

PHP-FPM RoadRunner

Documento simples

390 docs/s

2,605 docs/s

6.7x mais rápido

Fatura

294 docs/s

1,960 docs/s

6.7x mais rápido

Relatório de 100 páginas

14 docs/s

98 docs/s

7.0x mais rápido

4 Workers

1,500 docs/s

9,221 docs/s

6.1x mais rápido

PHP 8.5.3 + OPcache + JIT · Docker 4 CPUs / 16 GB · i9-13900K · Mediana de 20 execuções

Quando usar RoadRunner

O RoadRunner é recomendado quando você precisa de alto throughput (centenas de PDFs por minuto) ou baixa latência (tempos de resposta sub-milissegundo). Para aplicações web típicas gerando alguns PDFs por requisição, o PHP-FPM padrão é perfeitamente adequado.

Matriz de Decisão por Caso de Uso

Quais pacotes você deve instalar para seu caso de uso específico?

\u{2705} Recomendado\u{26AA} Opcional— N/A

Caso de Uso	Core	Artisan	Pro	Laravel	Symfony	CI4	Adaptation
Geração de Notas Fiscais e Relatórios	✅	⚪	⚪	⚪	⚪	⚪	—
E-commerce (HTML→PDF)	✅	✅	⚪	⚪	⚪	⚪	—
Documentos Acessíveis (PDF/UA)	✅	—	✅	⚪	⚪	⚪	—
Assinaturas Digitais (PAdES)	✅	—	✅	⚪	⚪	⚪	—
Migração do TCPDF Legado	✅	⚪	—	⚪	⚪	⚪	✅
API de Alta Vazão	✅	⚪	⚪	✅	✅	⚪	—
Conformidade de Arquivamento (PDF/A-4)	✅	—	✅	⚪	⚪	⚪	—
Documentos com Códigos de Barras	✅	—	⚪	⚪	⚪	⚪	—

Compatibilidade de Pacotes

A maioria dos pacotes funciona em conjunto sem problemas, com uma exceção:

Combinação	Compatível	Notas
Core + Qualquer pacote	Sim	Core é sempre obrigatório
Artisan + Qualquer framework	Sim	Chrome CDP funciona com todos os frameworks
Pro + Laravel/Symfony/CI	Sim	Recursos enterprise completos em qualquer framework
Pro + Adaptation	Não	Adaptation encapsula a API legada do TCPDF; Pro estende a API moderna do TCPDF-Next. Escolha uma abordagem.
Adaptation + Framework	Sim	Use Adaptation para migrar código legado dentro do seu framework

Considerações sobre CJK e Fontes

As 14 fontes básicas embutidas (Helvetica, Times, Courier, etc.) suportam apenas caracteres latinos. Se seus documentos precisam de texto em chinês, japonês ou coreano, você deve:

1. Incorporar fontes TrueType -- Use setFont() com uma fonte TTF que suporte seu conjunto de caracteres
2. Configurar caminhos de fontes -- Defina a variável de ambiente TCPDF_FONTS_DIR ou use a API de configuração
3. Considerar o tamanho do arquivo -- Fontes CJK são tipicamente de 5-15 MB cada; use font subsetting para reduzir o tamanho do PDF

// Example: Using a CJK font
$pdf = Document::createStandalone()
    ->addPage()
    ->setFont('/path/to/NotoSansCJK-Regular.ttf', '', 12)
    ->cell(0, 10, '你好世界 こんにちは 안녕하세요');

Fontes CJK Recomendadas

• Noto Sans CJK -- Família de fontes CJK open-source do Google (gratuita)
• Source Han Sans -- Equivalente da Adobe (gratuita)
• Ambas suportam chinês simplificado, chinês tradicional, japonês e coreano em um único arquivo de fonte.

Limitações de Hospedagem Compartilhada

Em hospedagem compartilhada, você tipicamente não pode:

• Instalar Chrome/Chromium (sem pacote Artisan)
• Executar processos de longa duração (sem RoadRunner)
• Instalar extensões PHP (limitado ao que é fornecido)

Configuração recomendada para hospedagem compartilhada:

composer require yeeefang/tcpdf-next

Use apenas o Core com o parser HTML embutido para necessidades básicas de HTML para PDF. Para renderização HTML pixel-perfect, considere fazer upgrade para um VPS.

Próximos Passos

• Primeiros Passos -- Instale e crie seu primeiro PDF
• Guia de Instalação -- Instalação detalhada para todos os pacotes
• Benchmarks -- Dados completos de comparação de performance
• Migração do TCPDF -- Guia de migração passo a passo