Integrazione di NextPDF con Symfony

In breve

Installare nextpdf/symfony, lasciare che Flex registri il bundle (oppure registrarlo manualmente), aggiungere config/packages/nextpdf.yaml e iniettare PdfFactory. Questa pagina funge da indice dell’integrazione. Ogni passaggio rimanda a una pagina di approfondimento.

Installazione

composer require nextpdf/symfony

Il bundle richiede nextpdf/core^3.0 || ^5.2, symfony/*^7.2 e psr/log^3.0. Le classi vengono caricate automaticamente sotto il prefisso PSR-4 NextPDF\Symfony\, mappato su src/Symfony/. Un autoloader PSR-4 risolve il prefisso del namespace verso questa directory di base (PSR-4 §2). Per i requisiti completi e i pacchetti facoltativi, vedere /integrations/symfony/install/.

Boot e auto-discovery

Con Symfony Flex, la voce extra.symfony.bundles nel composer.json del bundle registra NextPDF\Symfony\NextPdfBundle in tutti gli ambienti. Senza Flex, aggiungerlo manualmente a config/bundles.php:

return [
    NextPDF\Symfony\NextPdfBundle::class => ['all' => true],
];

Per la sequenza completa di boot e il comportamento del compiler pass, vedere /integrations/symfony/boot-and-discovery/.

Binding del container

Il file config/services.php del bundle registra questi servizi:

Servizio / alias	Ciclo di vita
`NextPDF\Symfony\Service\PdfFactory`	condiviso, pubblico — da iniettare
`nextpdf.document` → `PdfDocumentInterface` → `Document`	non condiviso, pubblico — nuovo a ogni risoluzione
`NextPDF\Contracts\FontRegistryInterface`	condiviso, bloccato dopo il warmup
`NextPDF\Graphics\ImageRegistry`	condiviso, `kernel.reset`
`NextPDF\Contracts\DocumentFactoryInterface`	condiviso
`NextPDF\Symfony\Http\PdfResponse`	helper pubblico stateless

Il binding del documento è intenzionalmente non condiviso. PSR-11 consente a un container di restituire un valore diverso su chiamate get() successive per lo stesso id. Un documento nuovo evita lo stato cross-request nei worker a esecuzione prolungata (PSR-11 §1.1.2). Per la tabella completa di servizi e alias, inclusi i binding EInvoice condizionali, vedere /integrations/symfony/configuration/.

Pubblicare la configurazione

L’alias di configurazione è nextpdf. Creare config/packages/nextpdf.yaml. Quando viene pubblicata una recipe Flex, viene depositata automaticamente una copia predefinita. Ogni chiave ha un valore predefinito, quindi un file minimo si presenta così:

nextpdf: ~

L’albero di configurazione completo è documentato in /integrations/symfony/configuration/.

Primo utilizzo

Iniettare PdfFactory, quindi restituire il risultato con PdfResponse:

<?php

declare(strict_types=1);

namespace App\Controller;

use NextPDF\Symfony\Http\PdfResponse;
use NextPDF\Symfony\Service\PdfFactory;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class PdfController
{
    #[Route('/hello.pdf', name: 'hello_pdf')]
    public function hello(PdfFactory $pdf): Response
    {
        $doc = $pdf->create();
        $doc->addPage();
        $doc->cell(0, 10, 'Hello from NextPDF on Symfony.');

        return PdfResponse::inline($doc, 'hello.pdf');
    }
}

Per il controller end-to-end e il flusso asincrono con Messenger, vedere /integrations/symfony/quickstart/.

Smoke test del bundle

Verificare il cablaggio senza scrivere codice applicativo:

php bin/console debug:container nextpdf
php bin/console debug:config nextpdf
php bin/console lint:container

debug:container nextpdf dovrebbe elencare PdfFactory, l’alias nextpdf.document e i registry. lint:container verifica che ogni argomento di servizio venga risolto. Per testare la generazione, aggiungere il controller precedente e quindi richiedere /hello.pdf.

Punti di ingresso dell’API pubblica

Questi sono i simboli pubblici supportati dal codice applicativo:

Simbolo	Scopo
`NextPDF\Symfony\Service\PdfFactory::create()`	`Document` nuovo e preconfigurato
`NextPDF\Symfony\Http\PdfResponse::inline()` / `download()`	risposta bufferizzata con header di sicurezza
`NextPDF\Symfony\Http\PdfResponse::streamInline()` / `streamDownload()`	risposta in streaming per chunk
`NextPDF\Symfony\Message\GeneratePdfMessage`	DTO di generazione asincrona (validato)
`NextPDF\Symfony\Message\PdfBuilderInterface`	contratto del builder risolto dall’handler

Conformità

Ogni riga contiene un’asserzione normativa formulata in questa pagina. Ogni asserzione è ancorata a un reference_id completo a 64 esadecimali proveniente dal corpus SDO con accesso controllato. La provenienza (manifest del corpus, transport di retrieval) si trova in _sidecars/rag-citations.yaml.

Specifica	Clausola	reference_id	Asserzione
PSR-11	`psr_11_container#1.1.2.p4`		Contratto dell’identificatore has()/get() del container
PSR-4	`psr_4_autoload#x1.x2.p5`		Mappatura del namespace dell’autoloader

Vedere anche

/integrations/symfony/install/ — requisiti e registrazione.
/integrations/symfony/boot-and-discovery/ — discovery, boot, compiler pass.
/integrations/symfony/configuration/ — schema completo e tabella dei servizi.
/integrations/symfony/quickstart/ — controller eseguibile ed esempio asincrono.
/integrations/symfony/production-usage/ — sicurezza dei worker e streaming.