Referencia de API de Laravel

De un vistazo

El paquete nextpdf/laravel integra en una aplicación de Laravel el core de NextPDF, independiente del framework. Expone cuatro elementos de uso directo: la fachada Pdf para la creación rápida, el binding de contenedor PdfDocumentInterface para la creación inyectable de documentos, el helper PdfResponse que convierte un documento terminado en una respuesta HTTP, y el job de cola GeneratePdfJob para la generación fuera de la solicitud. El NextPdfServiceProvider registra todos los bindings y se descubre automáticamente, por lo que no requiere configuración manual. La configuración en config/nextpdf.php controla los valores predeterminados, las fuentes, el encolado y las funciones opcionales de firma y TSA.

Punto de partida: para enviar un PDF directamente desde un controlador, construir un documento y devolver PdfResponse::download($document, 'file.pdf'); consultar el primer ejemplo más abajo.

Tareas comunes

Los siguientes fragmentos cubren los tres flujos más habituales al empezar. Cada uno está verificado con el código fuente del paquete; a continuación se incluyen las tablas exhaustivas por símbolo.

Devolver un PDF descargable desde un controlador: la tarea más habitual:

<?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(PdfDocumentInterface $document): Response
    {
        $document->addPage();
        $document->cell(0, 10, 'Monthly report', newLine: true);

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

Qué hace: inyecta un documento nuevo, escribe una línea y devuelve una respuesta de tipo attachment con Content-Type: application/pdf y los encabezados de seguridad de OWASP. Cambiar download() por inline() para mostrarlo en el navegador.

Crear y guardar con la fachada Pdf: la vía más directa para scripts y flujos breves:

<?php

declare(strict_types=1);

use NextPDF\Laravel\Facades\Pdf;

Pdf::addPage();
Pdf::cell(0, 10, 'Hello from Laravel', newLine: true);
Pdf::save(storage_path('app/hello.pdf'));

Qué hace: la fachada resuelve un documento nuevo desde el contenedor, escribe una celda y guarda en disco el PDF terminado.

Generar un PDF fuera del hilo de la solicitud con GeneratePdfJob:

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Laravel\Jobs\GeneratePdfJob;

GeneratePdfJob::dispatch(
    storage_path('app/reports/january-2026.pdf'),
    static fn (PdfDocumentInterface $document): PdfDocumentInterface => $document
        ->addPage()
        ->cell(0, 10, 'January report', newLine: true),
);

Qué hace: encola la generación en un worker. El closure de construcción recibe un documento resuelto por el contenedor y lo devuelve. El job valida la ruta de salida .pdf antes de guardar. El nombre de la cola, el timeout y la conexión provienen de config('nextpdf.queue.*').

Fachada

La fachada Pdf actúa como proxy estático sobre un Document nuevo del core; resulta adecuada en flujos breves de controlador cuando el estilo estático mejora la legibilidad. Cada fila corresponde a un método del documento delegado por proxy.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`NextPDF\Laravel\Facades\Pdf`	ninguno; el accessor estático de la fachada resuelve `NextPDF\Contracts\PdfDocumentInterface`	Laravel resuelve el binding de contenedor actual para la interfaz de documento.	La API fluida del documento del core subyacente.	Fallo de binding de contenedor de Laravel si el provider no está registrado.	Adecuada para flujos breves de controlador. Preferir la inyección por constructor para servicios y jobs.
`Pdf::setTitle(string $title)`	`title`: título del documento.	Reemplaza cualquier título anterior.	`static`	Errores de validación del core o en tiempo de escritura.	Se hace proxy hacia el `Document` del core.
`Pdf::setAuthor(string $author)`	`author`: metadatos de autor del documento.	Reemplaza cualquier autor anterior.	`static`	Errores de validación de metadatos del core.	Preferir los valores predeterminados configurados para los metadatos de toda la aplicación.
`Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)`	`size`: tamaño de página opcional; `orientation`: `Portrait` de forma predeterminada.	Usa el tamaño de página configured/default cuando se omite `size`.	`static`	Errores de validación de página del core.	Usar un `PageSize` explícito cuando el tamaño de salida importa.
`Pdf::setFont(string $family, string $style = '', float $size = 12.0)`	Familia de fuente, estilo y tamaño en puntos.	Estilo vacío y tamaño de 12 pt.	`static`	Errores del registro de fuentes o de codificación.	Precarga las fuentes de producción mediante `nextpdf.preload_fonts` cuando la latencia importa.
`Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)`	Caja de celda, texto, indicador de borde, indicador de salto de línea y alineación.	Texto vacío, sin borde, sin salto de línea y alineación a la izquierda.	`static`	Errores de maquetación o de codificación de texto.	Usarlo para salida sencilla de maquetación fija.
`Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)`	Ancho de celda, altura de línea, texto, indicador de borde y alineación.	Sin borde y alineación a la izquierda.	`static`	Errores de maquetación o de codificación de texto.	Usarlo cuando el texto deba ajustarse dentro de un ancho fijo.
`Pdf::writeHtml(string $html)`	`html`: fragmento de HTML.	Renderiza en la página actual y crea una cuando es necesario.	`static`	Errores de renderizado de HTML del core.	Aplicar políticas de tamaño de entrada y de recursos antes de aceptar HTML no confiable.
`Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)`	Ruta del archivo y rectángulo de colocación opcional.	Permite que el documento del core elija la posición actual y el tamaño intrínseco cuando se omiten las coordenadas.	`static`	Errores de decodificación de imagen, de ruta o de maquetación.	Validar la política de origen de imágenes antes de aceptar rutas proporcionadas por el usuario.
`Pdf::output(?string $filename = null, OutputDestination $dest = Inline)`	`filename`: nombre opcional; `dest`: destino de salida.	Salida inline cuando se omite el destino.	`string`	Errores de serialización del core.	Preferir `PdfResponse` para las respuestas HTTP de Laravel.
`Pdf::save(string $path)`	`path`: destino en el sistema de archivos.	Escribe el PDF terminado en disco.	`void`	Errores del sistema de archivos o de escritura del core.	Validar los directorios de salida en el código de la aplicación.
`Pdf::getPdfData()`	ninguno.	Materializa el PDF en memoria.	`string`	Errores de serialización del core.	Usarlo cuando otro objeto del framework deba ser dueño del cuerpo de la respuesta.

Service provider y bindings

Consultar esta tabla cuando haya que resolver o sobrescribir directamente una entrada del contenedor; por ejemplo, para inyectar DocumentFactoryInterface en un servicio o para comprobar qué servicios declara provides() como diferidos.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`NextPdfServiceProvider::register()`	ninguno.	Fusiona `config/nextpdf.php`, registra los registries, la document factory, el binding de documento, el cliente HTTP, el cliente TSA, el firmante y los contratos opcionales de factura electrónica.	`void`	Errores de resolución de contenedor o de clase opcional cuando se usa una función.	`FontRegistryInterface` e `ImageRegistry` son compartidos; los documentos siempre son nuevos.
`NextPdfServiceProvider::boot()`	ninguno.	Valida las extensiones de PHP requeridas y publica `nextpdf-config` en modo consola.	`void`	`RuntimeException` si una extensión requerida no está disponible.	Las extensiones requeridas son `mbstring` y `zlib`.
`NextPdfServiceProvider::provides()`	ninguno.	Devuelve los IDs de servicio diferidos.	`array<string>`	No se espera ninguno.	Incluye `PdfDocumentInterface`, `DocumentFactoryInterface`, `FontRegistryInterface`, `SignerInterface`, `TsaClient`, `ClientInterface` y `nextpdf`.
`PdfDocumentInterface` / `nextpdf`	se resuelve desde el contenedor de Laravel.	Crea un `Document` desechable a partir de `DocumentFactoryInterface`, luego aplica los valores predeterminados configurados y los ajustes opcionales de PDF/A o de Artisan.	`NextPDF\Core\Document`	Errores de extensión opcional cuando está configurada pero no disponible.	Resuelve un documento nuevo para cada solicitud o job.
`DocumentFactoryInterface`	se resuelve desde el contenedor de Laravel.	Factory singleton que comparte los registries de fuentes e imágenes con vida útil del proceso.	`DocumentFactoryInterface`	Errores de configuración de registry.	Usarlo para la inyección de dependencias explícita.
`SignerInterface`	se resuelve desde el contenedor de Laravel.	Devuelve `null` a menos que `nextpdf.signature.enabled` y las rutas de certificado estén configuradas.	`SignerInterface	null`	Errores de carga de certificado o de validación a nivel de firma.

Configuración

Usar esta tabla para consultar las claves nextpdf.* que los bindings leen en runtime; la referencia completa por clave, con variables de entorno y valores predeterminados, está en /integrations/laravel/configuration/.

Clave	Tipo	Comportamiento predeterminado	Notas
`nextpdf.fonts_path`	`string`	Usa las fuentes de recursos de Laravel cuando se omite.	Directorio para fuentes personalizadas y precalentamiento.
`nextpdf.cache_path`	`string`	Ruta de caché de la aplicación.	Mantenerla con permisos de escritura para el worker de PHP.
`nextpdf.preload_fonts`	`list<string>`	Lista vacía.	Las fuentes se precalientan durante la creación del registry y luego el registry se bloquea.
`nextpdf.image_cache_mb`	`int`	Tamaño acotado de la caché de imágenes.	Limita la memoria de la caché de imágenes con vida útil del proceso.
`nextpdf.defaults.*`	`array`	Creador `NextPDF`, idioma `en`, autor opcional y valores predeterminados de maquetación.	Se aplica a cada documento nuevo.
`nextpdf.artisan.*`	`array`	El renderer de Chrome está deshabilitado a menos que esté instalado y configurado.	Se mapea a `ChromeRendererConfig::fromArray()`.
`nextpdf.signature.*`	`array`	La firma está deshabilitada de forma predeterminada.	Certificado, clave privada, contraseña, certificados adicionales y nivel de firma.
`nextpdf.tsa.*`	`array`	TSA está deshabilitado cuando la URL está vacía.	Admite credenciales, archivos mTLS, timeout, pins de clave pública y política HTTP.
`nextpdf.ocsp_cache.*`	`array`	La caché OCSP está habilitada con el TTL configurado.	La usan los flujos de validación de firma cuando está disponible.

Respuestas HTTP

Usar esta tabla al devolver un documento terminado por HTTP y elegir entre visualización inline, descarga como adjunto o salida en streaming.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`PdfResponse::inline(Document $document, string $filename = 'document.pdf')`	`document`: documento construido; `filename`: nombre de archivo de Content-Disposition.	Los nombres de archivo vacíos se normalizan a `document.pdf`.	`Illuminate\Http\Response`	Errores de serialización del core o de construcción de la respuesta.	Establece el content type de PDF y encabezados defensivos.
`PdfResponse::download(Document $document, string $filename = 'document.pdf')`	Igual que `inline`; la disposition es attachment.	Respuesta de descarga del navegador.	`Illuminate\Http\Response`	Igual que `inline`.	Usarlo para descargas explícitas de archivos.
`PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')`	Igual que `inline`.	Materializa los bytes del PDF y luego emite fragmentos de 64 KB.	`Symfony\Component\HttpFoundation\StreamedResponse`	Igual que `inline`.	Se trata de salida HTTP en streaming, no de renderizado sin copia.
`PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')`	Igual que `streamInline`; la disposition es attachment.	Respuesta de stream de descarga.	`StreamedResponse`	Igual que `streamInline`.	Aplicar límites de tamaño de entrada y de salida antes de renderizar.

Job de cola

Usar esta tabla al mover la generación fuera del hilo de la solicitud; cubre la construcción, el dispatch y la asociación de callbacks de éxito o de fallo a GeneratePdfJob.

Símbolo	Parámetros	Comportamiento predeterminado	Devuelve	Lanza o falla con	Notas
`new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)`	`outputPath`: `.pdf` de destino; `builder`: recibe un `PdfDocumentInterface`; los callbacks son opcionales.	El nombre de la cola, el timeout y la conexión se leen de `config('nextpdf.queue.*')`.	Instancia del job.	Errores de serialización si el builder o los callbacks no se pueden serializar.	El builder debe devolver el documento configurado.
`GeneratePdfJob::handle()`	ninguno.	Resuelve `PdfDocumentInterface`, aplica el builder, valida la ruta de salida y luego guarda.	`void`	`InvalidArgumentException` para rutas de salida no seguras; errores de escritura del core.	Rechaza los stream wrappers, los bytes nulos, los segmentos `..` y las rutas que no sean `.pdf`.
`GeneratePdfJob::failed(Throwable $exception)`	`exception`: causa del fallo.	Llama al callback de fallo configurado cuando está presente.	`void`	Fallos en el callback.	Mantener los callbacks idempotentes.
`GeneratePdfJob::then(callable $callback)`	`callback`: recibe la ruta de salida.	Reemplaza el callback de éxito.	`self`	Errores de closure serializable.	Helper fluido para la configuración del dispatch.
`GeneratePdfJob::catch(callable $callback)`	`callback`: recibe el `Throwable` lanzado.	Reemplaza el callback de fallo.	`self`	Errores de closure serializable.	Usarlo para alertas o limpieza compensatoria.

Notas de desarrollo

PdfResponse siempre llama a getPdfData() antes de construir la respuesta. No construye documentos de forma diferida.
Los payloads de cola pueden manipularse en transportes compartidos; mantener las rutas de salida confinadas a un directorio propiedad de la aplicación.
Usar un documento nuevo por cada solicitud o job. No reutilizar un documento entre solicitudes.