Configurar NextPDF y renderizar tu primer PDF

NextPDF es una biblioteca de PHP que crea archivos PDF (Portable Document Format). En este tutorial se instala en una carpeta vacía y se renderiza el primer documento de una página. Se necesita un terminal y unos diez minutos.

Lo que se va a construir

Se construirá un proyecto diminuto que contiene un único script, 01-hello.php. El script renderiza una sola página con una línea de título en negrita y un párrafo. Guarda el resultado como out/hello.pdf. Por el camino se aprenden dos comandos que confirman que la instalación está en buen estado.

Esta página enseña una vía de instalación: una carpeta vacía más el paquete del motor. Existen otras vías, como los adaptadores de framework, los renderizadores basados en navegador y el cliente de Python. Estas se encuentran en Instalación y Elegir tu camino. Hoy no hacen falta.

Paso 1: Crear un proyecto e instalar NextPDF

Composer es el gestor de paquetes de PHP. Descarga bibliotecas en el proyecto y genera un autocargador. Un autocargador es un pequeño archivo PHP que localiza las clases de las bibliotecas, de modo que nunca haya que escribir largas listas de inclusiones.

Abrir un terminal y ejecutar estos tres comandos:

mkdir hello-nextpdf
cd hello-nextpdf
composer require nextpdf/core

Composer imprime el progreso mientras resuelve y descarga los paquetes. Las líneas exactas varían según la versión de Composer y la caché local. Una instalación correcta termina sin texto de error y tiene un aspecto parecido a este:

./composer.json has been created
Running composer update nextpdf/core
Loading composer repositories with package information
Updating dependencies
Lock file operations: ... installs, 0 updates, 0 removals
...
Generating autoload files

Qué acaba de suceder

Composer creó tres cosas en la carpeta. composer.json registra que el proyecto depende del motor. composer.lock fija la versión exacta que se instaló, de modo que una instalación posterior resuelva el mismo código. La carpeta vendor/ alberga los paquetes descargados, incluido vendor/autoload.php. El script carga ese único archivo y todas las clases del motor quedan disponibles.

Composer también comprobó la configuración de PHP durante la instalación. El motor declara las extensiones de PHP que necesita. Las extensiones son módulos opcionales integrados en PHP. Si falta alguna, Composer se detiene y la nombra en lugar de dejar una instalación defectuosa.

Paso 2: Renderizar el primer PDF

Crear un archivo llamado 01-hello.php junto a composer.json. Pegar en él este programa completo:

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

@mkdir(__DIR__ . '/out');

$document = Document::createStandalone();
$document->setTitle('Hello from NextPDF');
$document->addPage();

$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello from NextPDF', newLine: true);

$document->setFont('helvetica', '', 12);
$document->cell(0, 10, 'This page came from a short PHP script and the built-in fonts.', newLine: true);

$document->save(__DIR__ . '/out/hello.pdf');

echo "Wrote out/hello.pdf\n";

Ejecutarlo:

php 01-hello.php

Debería aparecer exactamente una línea:

Wrote out/hello.pdf

Abrir out/hello.pdf en cualquier visor de PDF. Se verá la línea de título en negrita con el párrafo debajo, y la mayoría de los visores muestran «Hello from NextPDF» en el título de su ventana.

Qué acaba de suceder

Recorrer el script de arriba abajo:

• require carga el autocargador de Composer, de modo que la clase Document se resuelve.
• @mkdir crea la carpeta out/. La @ inicial mantiene el script en silencio cuando la carpeta ya existe, de modo que se pueda ejecutar de nuevo.
• Document::createStandalone() devuelve un documento nuevo. Está pensado para scripts de línea de comandos cortos exactamente como este.
• setTitle() establece el título del documento, que los visores muestran en el título de la ventana.
• addPage() añade una página vacía y coloca el cursor en la esquina superior izquierda.
• setFont() elige una familia tipográfica, un estilo y un tamaño en puntos. Los puntos son la unidad estándar para los tamaños de fuente en impresión. 'B' significa negrita y '' significa normal. La familia llamada helvetica está integrada, de modo que no hacen falta archivos de fuentes.
• cell() escribe una línea de texto en la posición del cursor. Un ancho de 0 significa «estirar hasta el margen derecho». newLine: true desplaza el cursor hacia abajo después, como pulsar Enter.
• save() construye el PDF terminado y lo escribe en el disco.

Un documento produce un archivo. Cuando se necesite un segundo PDF, crear un documento nuevo en lugar de reutilizar el anterior.

Paso 3: Verificar la configuración

Dos comprobaciones rápidas confirman que esta instalación seguirá funcionando más allá de un único script.

Primero, listar las extensiones que lleva PHP:

php -m

Buscar en la lista curl, gd, intl, mbstring, openssl y zlib. El motor depende de estas seis. Composer ya las comprobó en el Paso 1, así que todas deberían aparecer.

Segundo, ejecutar la propia comprobación de estado del motor:

vendor/bin/nextpdf doctor

En Windows, llamar a vendor\bin\nextpdf doctor en su lugar. El comando inspecciona la versión de PHP, las extensiones, la carpeta temporal y la configuración. Cada comprobación imprime [OK], [WARN] o [FAIL], seguida de un veredicto general.

Qué acaba de suceder

Leer primero el bloque Extensions. Seis líneas [OK] con los nombres curl, gd, intl, mbstring, openssl y zlib significan que la instalación está lista para todos los tutoriales que siguen.

El informe también enumera las capacidades del motor. En la instalación gratuita de Core, las capacidades que pertenecen a los paquetes comerciales imprimen [FAIL] con un mensaje que nombra el paquete que las proporciona. Eso es lo esperado aquí y puede cambiar el veredicto general a UNHEALTHY aunque la configuración de Core esté bien. Para estos tutoriales, el bloque Extensions es la señal que importa.

Si algo salió mal

Cotejar primero el síntoma con estos casos habituales:

• composer: command not found significa que Composer falta o no está en el PATH. Instalarlo desde getcomposer.org y luego repetir el Paso 1.
• Failed opening required '.../vendor/autoload.php' significa que el script se ejecutó fuera de la carpeta del proyecto, o que la instalación no terminó. Entrar en la carpeta del Paso 1 y ejecutar composer install.
• Si Composer se detiene durante el Paso 1 y nombra una extensión de PHP que falta, habilitar esa extensión en el php.ini. Confirmarlo con php -m, y luego repetir la instalación.
• Una línea [FAIL] en el bloque Extensions del doctor nombra una extensión de PHP que falta. Habilitarla en php.ini, confirmar con php -m y ejecutar el doctor de nuevo. Las líneas [FAIL] de capacidad que nombran un paquete comercial son las esperadas en la instalación de Core y no requieren acción aquí.

Para cualquier otra cosa, empezar por la base de conocimiento de resolución de problemas. Si un script lanza una excepción, buscar su clase en la referencia de errores; la mayoría de los errores de principiante aparecen en errores generales.

Siguiente

Ya hay una instalación funcional y el primer archivo renderizado. Continuar con Texto, fuentes y conceptos básicos de página para controlar los tamaños de página, las fuentes integradas, los colores y la alineación.