Il primo PDF

In breve

In questo tutorial si generano due file PDF. Nel primo si scrive il testo direttamente con l’Application Programming Interface (API) fluente del core. Nel secondo si esegue il rendering in pagina di un frammento di HyperText Markup Language (HTML) e Cascading Style Sheets (CSS). Al termine si dispone di uno script funzionante, adattabile a un documento reale, e si saprà dove trovare le varianti per framework e quella server.

Entrambi gli approcci si basano sullo stesso motore. Pertanto quanto appreso qui vale per ogni distribuzione.

Il diagramma seguente mostra i due approcci di creazione e le tre superfici di distribuzione che li riutilizzano.

From your code to a PDF file

Prima di iniziare

Servono due elementi: il motore del core installato e un ambiente in cui eseguire uno script PHP.

1. Verificare che PHP 8.4 sia il runtime attivo:

   php --version

2. Installare il motore del core nel progetto, se non è già presente:

   composer require nextpdf/core

3. Creare un file di lavoro denominato first-pdf.php nella radice del progetto.

I 14 font standard funzionano senza configurazione

Il font predefinito del corpo del testo viene risolto in uno dei 14 font Type 1 standard indicati in ISO 32000-2. Di conseguenza, il primo documento non richiede file di font. I font personalizzati si registrano e si incorporano in seguito, quando il design lo richiede.

Generare un PDF da PHP

Iniziare dall’API fluente. Document::createStandalone() restituisce un documento pronto all’uso. Si aggiunge una pagina, si imposta un font, si scrivono le celle e quindi si salva. Ogni metodo di creazione restituisce il documento, quindi la sequenza di chiamate si legge dall’alto verso il basso.

1. Inserire questo codice in first-pdf.php. Lo script abilita la tipizzazione strict, carica l’autoloader e crea un documento di una pagina:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('My first NextPDF document');
   $document->addPage();
   
   $document->setFont('helvetica', 'B', 24);
   $document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
   
   $document->setFont('helvetica', '', 12);
   $document->cell(0, 10, 'This is the first PDF I generated with PHP.', newLine: true);
   
   $document->save(__DIR__ . '/first-pdf.pdf');
   
   echo "Wrote first-pdf.pdf\n";

2. Eseguire lo script:

   php first-pdf.php

3. Verificare l’output. Nell’output standard dovrebbe comparire questa riga e, accanto allo script, dovrebbe essere creato un nuovo file denominato first-pdf.pdf:

   Wrote first-pdf.pdf

A questo punto è stato generato un file PDF 2.0 valido. Aprendolo in un visualizzatore qualsiasi, si vedono il titolo e la riga sottostante.

save rispetto a output

save() scrive il documento in un percorso di file. Per inviare i byte in streaming a un browser, chiamare invece output(). Per acquisirli in memoria, chiamare getPdfData(). Un documento è monouso: dopo averne scritto uno, creare una nuova istanza per il documento successivo invece di riutilizzarlo.

Eseguire il rendering di HTML in PDF

La scrittura delle celle offre un controllo preciso. Tuttavia, la maggior parte dei documenti si definisce più rapidamente in HTML e CSS. Il motore del core include una pipeline HTML in puro PHP. Il metodo writeHtml() esegue il rendering di un frammento nella pagina corrente. Non usa alcun browser né alcun servizio esterno.

1. Creare un secondo file, html-pdf.php, che esegue il rendering di un frammento HTML:

   <?php
   
   declare(strict_types=1);
   
   require_once __DIR__ . '/vendor/autoload.php';
   
   use NextPDF\Core\Document;
   
   $document = Document::createStandalone();
   $document->setTitle('HTML to PDF');
   $document->addPage();
   
   $html = <<<'HTML'
   <h1 style="color: #1E3A8A;">HTML rendering in NextPDF</h1>
   <p>NextPDF renders <strong>HTML content</strong> directly into PDF pages.</p>
   <ul>
       <li>Headings, paragraphs, and lists</li>
       <li>Inline <strong>bold</strong> and <em>italic</em></li>
       <li>Inline styles such as color and font-size</li>
   </ul>
   HTML;
   
   $document->writeHtml($html);
   
   $document->save(__DIR__ . '/html-pdf.pdf');
   
   echo "Wrote html-pdf.pdf\n";

2. Eseguirlo:

   php html-pdf.php

3. Verificare la riga di output e il nuovo file:

   Wrote html-pdf.pdf

Trattare l’input HTML come non attendibile

Quando l’HTML proviene da un utente, da un modulo o da qualsiasi fonte esterna, convalidarlo e sanificarlo prima di passarlo a writeHtml(). La ricetta Eseguire il rendering di HTML in una pagina PDF illustra l’approccio completo alla sicurezza e il modello di streaming.

Il motore esegue il rendering di un sottoinsieme supportato di HTML e CSS. Prima di fare affidamento su una proprietà, verificarla nella matrice di supporto CSS. Quando un layout richiede la piena fedeltà di un browser, ad esempio per flexbox, grid o web font, installare l’Artisan renderer e chiamare invece writeHtmlChrome(). Questo metodo mantiene il testo selezionabile.

Da un controller di un framework

L’applicazione può già basarsi su un framework o fungere da server. Le stesse due chiamate si possono trasferire in quell’ambiente. Il motore resta identico; cambia solo il cablaggio.

Laravel

La facade Pdf risolve un nuovo documento a ogni chiamata. PdfResponse converte un documento in una risposta di download:

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

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

Consultare la guida rapida di Laravel.

Symfony

Il bundle espone un servizio PdfFactory. Usare il type-hint NextPDF\Symfony\Service\PdfFactory in un controller, creare un documento nello stesso modo e restituirlo come risposta HTTP. Consultare la guida rapida di Symfony.

Server (REST)

Con NextPDF Server in esecuzione, inviare tramite POST un array ordinato di operazioni; il server restituisce i byte del PDF:

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

Con una risposta 200, il corpo contiene il PDF. Consultare la guida rapida di Connect.

Passaggi successivi

A questo punto è stato generato un PDF in tre modi. Ecco come proseguire da ciascun percorso.

Eseguire il rendering di HTML in una pagina PDF La ricetta HTML completa: elementi supportati, modello di streaming e postura di sicurezza.

Scegliere il percorso Decidere tra core, un framework e il server, e quale renderer HTML utilizzare.

Riferimento del motore del core Tutti i metodi, i parametri e i valori restituiti di Document.

Cookbook Ricette orientate alle attività per stile, tabelle, impaginazione e altro ancora.