Tu primer PDF

De un vistazo

En este tutorial se generan dos archivos PDF. Para el primero, se escribe texto directamente con la API fluida del core. Para el segundo, se renderiza un fragmento de HTML y CSS en una página. Al final, queda un script funcional que se puede adaptar a un documento real. También se verá dónde están las variantes de framework y la variante de servidor.

Ambos enfoques se ejecutan sobre el mismo motor. Por eso, lo aprendido aquí se traslada a cada distribución.

El siguiente diagrama muestra los dos enfoques de autoría y las tres superficies de despliegue que los reutilizan.

From your code to a PDF file

Antes de empezar

Se necesitan dos cosas: el motor del core instalado y un lugar donde ejecutar un script PHP.

1. Confirmar que PHP 8.4 es el runtime activo:

   php --version

2. Instalar el motor del core en el proyecto, si todavía no está presente:

   composer require nextpdf/core

3. Crear un archivo de trabajo llamado first-pdf.php en la raíz del proyecto.

Las 14 fuentes estándar funcionan sin configuración

La fuente de cuerpo predeterminada se resuelve como una de las 14 fuentes Type 1 estándar nombradas en ISO 32000-2. Por eso, el primer documento no necesita archivos de fuentes. Las fuentes personalizadas se registran e incrustan más adelante, cuando un diseño las requiera.

Generar un PDF desde PHP

Se empieza con la API fluida. Document::createStandalone() devuelve un documento listo para usar. Se agrega una página, se define una fuente, se escriben celdas y luego se guarda. Cada método de autoría devuelve el documento, así que las llamadas se leen de arriba abajo.

1. Poner este código en first-pdf.php. El script declara tipos estrictos, carga el autoloader y construye un documento de una página:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. Ejecutar el script:

   php first-pdf.php

3. Confirmar la salida. Debería aparecer esta línea en la salida estándar y un archivo nuevo llamado first-pdf.pdf junto al script:

   Wrote first-pdf.pdf

Con esto, se genera un archivo PDF 2.0 válido. Al abrirlo en cualquier visor, se ve el encabezado con la línea debajo.

save frente a output

save() escribe el documento en una ruta de archivo. Para transmitir los bytes a un navegador, se llama a output(). Para capturarlos en memoria, se llama a getPdfData(). Un documento es de un solo uso: una vez escrito, crear una instancia nueva para el siguiente documento en lugar de reutilizarlo.

Renderizar HTML a PDF

Escribir celdas ofrece un control preciso. Sin embargo, la mayoría de los documentos se expresan más rápido como HTML y CSS. El motor del core incluye un pipeline de HTML en PHP puro. Su método writeHtml() renderiza un fragmento en la página actual. No usa ningún navegador ni ningún servicio externo.

1. Crear un segundo archivo, html-pdf.php, que renderiza un fragmento de HTML:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. Ejecutarlo:

   php html-pdf.php

3. Confirmar la línea de salida y el archivo nuevo:

   Wrote html-pdf.pdf

Tratar la entrada de HTML como no confiable

Cuando el HTML proviene de un usuario, de un formulario o de cualquier fuente externa, debe validarse y sanearse antes de pasarlo a writeHtml(). La recipe Renderizar HTML a una página PDF cubre la postura de seguridad completa y el modelo de transmisión.

El motor renderiza un subconjunto compatible de HTML y CSS. Antes de depender de una propiedad, conviene verificarla en la matriz de compatibilidad de CSS. Cuando un diseño necesita la fidelidad completa de un navegador (por ejemplo flexbox, grid o fuentes web), se instala el renderer de Artisan y se llama a writeHtmlChrome() en su lugar. Ese método conserva el texto seleccionable.

Desde un controlador de framework

La aplicación quizá ya se ejecute sobre un framework o como servidor. Las mismas dos llamadas se trasladan a ese entorno. El motor sigue siendo idéntico; solo cambia el cableado.

Laravel

La fachada Pdf resuelve un documento nuevo en cada llamada. PdfResponse convierte un documento en una respuesta de descarga:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use Illuminate\Http\Response;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Http\PdfResponse;

final class ReportController extends Controller
{
    public function download(): Response
    {
        $document = app(PdfDocumentInterface::class);
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

        return PdfResponse::download($document, 'report.pdf');
    }
}

Consultar el inicio rápido de Laravel.

Symfony

El bundle expone un servicio PdfFactory. Indicar el tipo NextPDF\Symfony\Service\PdfFactory en un controlador, construir un documento de la misma manera y luego devolverlo como una respuesta HTTP. Consultar el inicio rápido de Symfony.

Servidor (REST)

Con NextPDF Server en ejecución, se envía un POST con un arreglo ordenado de operaciones y el servidor devuelve los bytes del PDF:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

En una respuesta 200, el cuerpo contiene el PDF. Consultar el inicio rápido de Connect.

Próximos pasos

Ya se ha generado un PDF de tres maneras. Estos son los siguientes pasos para cada enfoque.

Renderizar HTML a una página PDF La recipe completa de HTML: elementos compatibles, el modelo de transmisión y la postura de seguridad.

Elige tu camino Decide entre el core, un framework, el servidor y qué renderer de HTML usar.

Referencia del motor del core Cada método, parámetro y valor de retorno de Document.

Cookbook Recipes orientadas a tareas para estilos, tablas, paginación y más.