Paquete Artisan
El paquete Artisan (yeeefang/tcpdf-next-artisan) proporciona conversión pixel-perfect de HTML a PDF impulsada por Chrome DevTools Protocol (CDP). Renderiza HTML con soporte completo de CSS3 -- incluyendo Flexbox, Grid, web fonts, media queries y animaciones congeladas al momento del renderizado.
Cuándo usar Artisan
| Escenario | Recomendado |
|---|---|
| Generar PDF desde plantillas HTML/CSS | Artisan |
| Construcción programática de PDF (celdas, dibujo) | Core |
| Emails HTML a archivo PDF | Artisan |
| Factura desde datos estructurados | Core o Artisan |
| Diseños CSS complejos (Grid, Flexbox) | Artisan |
| PDFs firmados/cifrados | Core |
Cómo funciona
Artisan lanza una instancia de Chrome headless via Chrome DevTools Protocol, carga tu contenido HTML en una página del navegador y usa la funcionalidad integrada de impresión a PDF de Chrome. Esto significa que cada característica CSS que Chrome soporta está disponible para tus PDFs -- sin más lucha con parsers CSS limitados.
HTML/CSS --> ChromeBridge --> Chrome CDP --> PDF binary --> save / streamInstalación
composer require yeeefang/tcpdf-next-artisanRequisitos:
- PHP 8.2+
chrome-php/chrome ^1.15(se instala automáticamente)- Navegador Chrome o Chromium instalado en el host
# Ubuntu/Debian
apt-get install -y chromium-browser
# macOS
brew install --cask chromium
# Windows (Chocolatey)
choco install googlechrome
# Set a custom path via environment variable
export CHROME_PATH=/usr/bin/google-chromeInicio rápido
use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
$renderer = HtmlRenderer::create();
$renderer
->loadHtml('<h1>Hello, World!</h1><p>Rendered with Chrome CDP.</p>')
->save('/output/hello.pdf');Desde una URL
HtmlRenderer::create()
->loadUrl('https://example.com/report')
->save('/output/report.pdf');Desde un archivo
HtmlRenderer::create()
->loadFile('/templates/invoice.html')
->save('/output/invoice.pdf');Contenido del paquete
| Clase | Propósito |
|---|---|
HtmlRenderer | Punto de entrada principal -- cargar HTML, configurar, renderizar |
ChromeBridge | Comunicación con Chrome DevTools Protocol |
RenderOptions | Configuración de renderizado (márgenes, escala, encabezados) |
PageSetup | Tamaño de página y orientación para renderizado |
PdfMerger | Fusionar múltiples páginas renderizadas en un solo PDF |
StyleInjector | Inyectar hojas de estilo CSS antes del renderizado |
ScreenshotCapture | Capturar capturas de pantalla de la página (PNG/JPEG) |
Jerarquía de excepciones
| Excepción | Cuándo |
|---|---|
RenderException | Fallo genérico de renderizado |
ChromeNotFoundException | Binario de Chrome no encontrado en la ruta esperada |
TimeoutException | La carga de página o el renderizado excedió el timeout configurado |
Todas las excepciones residen bajo el namespace Yeeefang\TcpdfNext\Artisan\Exceptions y extienden una clase base común ArtisanException.
Comparación con el parser HTML de Core
El paquete Core incluye un módulo HtmlParser para conversión básica de HTML a PDF. Úsalo cuando necesites una solución sin dependencias. Usa Artisan cuando necesites fidelidad completa de renderizado del navegador.
| Característica | Core HtmlParser | Artisan |
|---|---|---|
| Dependencia externa | Ninguna | Chrome/Chromium |
| CSS Flexbox / Grid | No | Sí |
Web fonts (@font-face) | No | Sí |
| Media queries | No | Sí |
| Ejecución de JavaScript | No | Sí |
Reglas CSS @page | No | Sí |
| Rendimiento (docs simples) | Más rápido | Más lento |
| Rendimiento (CSS complejo) | N/A | Confiable |
Próximos pasos
- HTML Renderer -- Carga y renderizado de contenido HTML.
- Render Options -- Configuración de tamaño de página, márgenes, encabezados y pies de página.
- Funciones avanzadas -- Fusión de PDFs, inyección de CSS, capturas de pantalla.
- Configuración Docker -- Ejecutar Artisan en contenedores.