Installazione del bundle Symfony di NextPDF

In sintesi

Installare il bundle con Composer. In un’applicazione con Symfony Flex, la registrazione è automatica. In un’applicazione senza Flex, registrarlo una sola volta in config/bundles.php.

Requisiti

I vincoli riportati di seguito derivano dal composer.json del bundle.

Dipendenza	Vincolo
php	>=8.4 <9.0
nextpdf/core	^3.0 || ^5.2
symfony/framework-bundle	^7.2
symfony/dependency-injection	^7.2
symfony/config	^7.2
symfony/http-foundation	^7.2
psr/log	^3.0

Il bundle verifica inoltre la presenza di due estensioni PHP in fase di build del container: ext-mbstring ed ext-zlib. Entrambe sono abilitate in tutti i runtime PHP supportati. Se una delle due è assente, la verifica fallisce immediatamente con un messaggio chiaro.

Pacchetti facoltativi

Questi pacchetti sono dichiarati nella sezione suggest del composer.json del bundle. Se presenti, abilitano funzionalità aggiuntive:

Pacchetto	Aggiunge
nextpdf/artisan	Rendering HTML tramite Chrome CDP, con rilevamento automatico in fase di compilazione
nextpdf/premium	Archiviazione PDF/A e firma digitale (installa il livello Pro), con rilevamento automatico in fase di compilazione
symfony/messenger	Generazione asincrona di PDF tramite l’handler Messenger

Installazione con Composer

composer require nextpdf/symfony

Il bundle viene caricato tramite autoload con il prefisso PSR-4 NextPDF\Symfony\, mappato su src/Symfony/. Questa mappatura è dichiarata in composer.jsonautoload.psr-4. L’autoloader generato da Composer mappa il prefisso del namespace su tale directory di base, secondo quanto definito dalla specifica dell’autoloader PSR-4 — vedere PSR-4 §2.

Registrazione del bundle

Symfony Flex (consigliato)

Il bundle include un’indicazione per la registrazione automatica in composer.json:

{
    "extra": {
        "symfony": {
            "bundles": {
                "NextPDF\\Symfony\\NextPdfBundle": "all"
            }
        }
    }
}

In un’applicazione con Flex abilitato, questa voce aggiunge il bundle a config/bundles.php per ogni ambiente (all). Non è necessario modificare il file manualmente. Per il modello di registrazione, consultare la documentazione ufficiale dei bundle Symfony (https://symfony.com/doc/current/bundles.html).

Registrazione manuale (senza Flex)

Se l’applicazione non utilizza Symfony Flex, aggiungere manualmente il bundle a config/bundles.php:

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

La classe del bundle è NextPDF\Symfony\NextPdfBundle. Estende la classe base Symfony Symfony\Component\HttpKernel\Bundle\Bundle. Il metodo getPath() del bundle restituisce la radice del pacchetto. Il metodo build() registra il compiler pass OptionalExtensionPass.

Fornire il file di configurazione

L’alias di configurazione del bundle è nextpdf. Creare config/packages/nextpdf.yaml. Una volta pubblicata, una recipe Flex deposita in questa posizione una copia predefinita. Un file minimale che si basa interamente sui valori predefiniti integrati ha la forma seguente:

nextpdf: ~

Ogni chiave ha un valore predefinito, quindi una configurazione vuota è valida. La pagina /integrations/symfony/configuration/ documenta l’intero albero di configurazione.

Verificare l’installazione

Verificare che il container rilevi i servizi del bundle:

php bin/console debug:container nextpdf

Dovrebbero essere visualizzati servizi che includono l’alias nextpdf.document e NextPDF\Symfony\Service\PdfFactory. Per esaminare la configurazione risolta, eseguire:

php bin/console debug:config nextpdf

Il comando stampa l’albero di configurazione unito, ovvero le sostituzioni definite dall’applicazione più i valori predefiniti.

Casi limite e insidie

• Intervallo del vincolo per core — il bundle accetta nextpdf/core^3.0 || ^5.2. Composer seleziona la versione che soddisfa il resto del grafo delle dipendenze. Vincolare una singola versione major nel composer.json della propria applicazione se è necessaria una versione deterministica del motore.
• Controllo delle estensioni mancanti — se php bin/console fallisce all’avvio con un messaggio relativo a ext-mbstring o ext-zlib, abilitare l’estensione indicata in php.ini. Si tratta di un comportamento fail-fast intenzionale, non di un difetto del bundle.
• Flex non ha registrato il bundle — svuotare la cache di Composer e reinstallare. Se non si utilizza Flex, seguire la procedura manuale con config/bundles.php.

Conformità

Ogni riga è un’asserzione normativa formulata in questa pagina, ancorata a un reference_id completo a 64 caratteri esadecimali proveniente dal corpus SDO ad accesso riservato. La provenienza si trova in _sidecars/rag-citations.yaml e copre il manifest del corpus e il trasporto di recupero.

Specifica	Clausola	reference_id	Asserzione
PSR-4	psr_4_autoload#x1.x2.p5		Mappatura da prefisso di namespace a directory per l’autoloader

Vedere anche

• /integrations/symfony/overview/ — funzionalità offerte dal bundle.
• /integrations/symfony/configuration/ — albero di configurazione completo e tabella dei servizi.
• /integrations/symfony/quickstart/ — primo controller eseguibile.
• /integrations/symfony/boot-and-discovery/ — sequenza dettagliata di discovery e avvio.