Integración de NextPDF en Laravel

De un vistazo

Esta guía práctica muestra cómo integrar NextPDF de extremo a extremo en una aplicación Laravel 12. El recorrido cubre seis etapas: instalar el paquete, dejar que Laravel lo descubra automáticamente, publicar la configuración, resolver los enlaces del contenedor, devolver una respuesta HTTP y ejecutar un trabajo en cola. Cada etapa enlaza con la referencia detallada de su área.

Instalación

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Arranque y descubrimiento automático

Laravel descubre automáticamente el proveedor de servicios y el alias de la facade a partir del bloque composer.jsonextra.laravel del paquete. No es necesario editar config/app.php. El mapa de autoload contiene una única entrada PSR-4. El prefijo NextPDF\Laravel\ se resuelve a src/Laravel/, según la regla PSR-4 de mapeo de prefijo a directorio base (PSR-4 §3). El proveedor es diferido (deferred): arranca cuando se resuelve por primera vez una de sus entradas de provides(). Los detalles internos completos del descubrimiento están en /integrations/laravel/boot-and-discovery/.

Enlaces del contenedor

El contrato del documento se resuelve desde el contenedor. Un identificador enlazado se resuelve a su entrada registrada (PSR-11 §1.1.2). El enlace del documento es una factory, por lo que cada resolución entrega un documento nuevo. Los registros de fuentes e imágenes son singletons, por lo que cada resolución devuelve la misma instancia compartida. La tabla completa de tiempos de vida de los enlaces está en /integrations/laravel/overview/ y /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

Publicar la configuración

php artisan vendor:publish --tag=nextpdf-config

Este comando escribe config/nextpdf.php. Cada clave, su variable de entorno y su valor predeterminado están documentados en /integrations/laravel/configuration/.

Prueba de humo del proveedor de servicios y del bundle

El paquete incluye una suite de pruebas basada en Testbench que prueba el proveedor de extremo a extremo. Esta es una prueba de humo mínima que se puede añadir a una aplicación consumidora:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Estas dos aserciones reflejan las comprobaciones de conformidad de uso único que hace el propio EInvoiceServiceProviderIntegrationTest del paquete. Confirman que el documento está enlazado como factory y que el registro de fuentes es un singleton bloqueado.

Puntos de entrada de la API pública

Punto de entrada	Propósito	Referencia
`NextPDF\Laravel\Facades\Pdf`	Proxy estático hacia un documento nuevo	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Documento resuelto por el contenedor	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Respuestas HTTP en línea / de descarga / por streaming	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Generación en cola	/integrations/laravel/production-usage/

Ejemplo de código — Producción

El controlador, cableado mediante inyección de dependencias y con manejo de errores, está documentado en detalle en /integrations/laravel/production-usage/. También se documenta el trabajo en cola, con sus callbacks de éxito y de fallo.

Casos límite y trampas

Resolver PdfDocumentInterface, no la clase concreta Document. Esto mantiene el enlace verificable e intercambiable.
SignerInterface y TsaClient se resuelven a null hasta que se configuran. Comprobar siempre si es null.
Los contratos de e-invoice requieren nextpdf/premium. Están enlazados, pero fallan al resolverse por primera vez si no está presente.

Rendimiento

El cableado de extremo a extremo no añade costo de arranque, porque el proveedor es diferido. Los costos de construcción en la primera resolución y los costos de precalentamiento de fuentes se tratan en /integrations/laravel/boot-and-discovery/.

Notas de seguridad

PdfResponse aplica un conjunto fijo de encabezados OWASP. GeneratePdfJob valida su ruta de salida en el worker. El modelo de amenazas está en /integrations/laravel/security-and-operations/.

Conformidad

Afirmación	Fuente	Cláusula	reference_id
El identificador enlazado se resuelve a su entrada registrada	Contenedor PSR-11	§1.1.2
El prefijo PSR-4 se mapea al directorio base	Autoloader PSR-4	§3

Contexto comercial

Los contratos de firma, PDF/A y e-invoice se integran a través del mismo proveedor cuando nextpdf/premium está instalado. Se trata de una capacidad opcional de Enterprise. El paquete Core documentado aquí no necesita ningún cambio de código para adoptarla. Consulta https://nextpdf.dev/get-license/?intent=laravel-signing.

Véase también

/integrations/laravel/overview/ — arquitectura y tabla de enlaces
/integrations/laravel/install/ — instalación y extensiones opcionales
/integrations/laravel/quickstart/ — primer ejemplo ejecutable
/integrations/laravel/production-usage/ — DI, manejo de errores, cola
/integrations/laravel/boot-and-discovery/ — descubrimiento y tiempos de vida