Twój pierwszy plik PDF

W skrócie

W tym samouczku wygenerujesz dwa pliki PDF. Najpierw zapiszesz tekst bezpośrednio za pomocą fluent API rdzenia. Następnie wyrenderujesz na stronie fragment HTML z CSS. Na koniec będziesz mieć działający skrypt, który można dostosować do rzeczywistego dokumentu, oraz odnośniki do wariantów dla frameworków i serwera.

Oba podejścia działają na tym samym silniku, więc to, czego nauczysz się tutaj, przyda się w każdej dystrybucji.

Poniższy diagram pokazuje dwa podejścia do tworzenia treści oraz trzy środowiska wdrożeniowe, które z nich korzystają.

From your code to a PDF file

Zanim zaczniesz

Potrzebujesz zainstalowanego silnika rdzeniowego oraz środowiska, w którym uruchomisz skrypt PHP.

1. Sprawdź, czy PHP 8.4 jest aktywnym środowiskiem uruchomieniowym:

   php --version

2. Zainstaluj silnik rdzeniowy w projekcie, jeśli nie jest jeszcze obecny:

   composer require nextpdf/core

3. Utwórz w katalogu głównym projektu plik roboczy o nazwie first-pdf.php.

14 standardowych czcionek działa bez konfiguracji

Domyślny krój tekstu głównego jest mapowany na jedną z 14 standardowych czcionek Type 1 wymienionych w ISO 32000-2. Twój pierwszy dokument nie wymaga żadnych plików czcionek. Niestandardowe czcionki zarejestruj i osadź później, gdy będzie tego wymagać projekt.

Generowanie pliku PDF z PHP

Zacznij od fluent API. Document::createStandalone() zwraca dokument gotowy do użycia. Dodaj stronę, ustaw czcionkę, wstaw komórki, a następnie zapisz dokument. Każda metoda dodająca treść zwraca dokument, dzięki czemu wywołania czyta się od góry do dołu.

1. Umieść ten kod w first-pdf.php. Skrypt deklaruje ścisłe typy, ładuje autoloader i tworzy jedną stronę:

   <?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. Uruchom skrypt:

   php first-pdf.php

3. Sprawdź wynik. Na standardowym wyjściu powinien pojawić się ten wiersz oraz nowy plik o nazwie first-pdf.pdf obok skryptu:

   Wrote first-pdf.pdf

Masz teraz prawidłowy plik PDF 2.0. Otwórz go w dowolnej przeglądarce, aby zobaczyć nagłówek i wiersz pod nim.

save kontra output

save() zapisuje dokument pod wskazaną ścieżką pliku. Aby zamiast tego przesłać strumieniowo bajty do przeglądarki, wywołaj output(). Aby przechwycić bajty w pamięci, wywołaj getPdfData(). Dokumentu można użyć tylko raz. Po zapisaniu dokumentu utwórz nową instancję dla kolejnego dokumentu, zamiast używać tej samej ponownie.

Renderowanie HTML do PDF

Komórki dają precyzyjną kontrolę, ale większość dokumentów szybciej opisuje się w HTML i CSS. Silnik rdzeniowy zawiera potok HTML napisany w czystym PHP. Metoda writeHtml() renderuje fragment na bieżącej stronie. Nie korzysta z przeglądarki ani z zewnętrznej usługi.

1. Utwórz drugi plik, html-pdf.php, renderujący fragment 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. Uruchom go:

   php html-pdf.php

3. Potwierdź wiersz wyjściowy oraz nowy plik:

   Wrote html-pdf.pdf

Traktuj dane wejściowe HTML jako niezaufane

Gdy HTML pochodzi od użytkownika, z formularza albo z dowolnego źródła zewnętrznego, zwaliduj go i oczyść, zanim przekażesz go do writeHtml(). Przepis Renderowanie HTML na stronę PDF omawia pełne zabezpieczenia oraz model strumieniowania.

Silnik renderuje obsługiwany podzbiór HTML i CSS. Zanim oprzesz układ na konkretnej właściwości, sprawdź macierz obsługi CSS. Gdy układ wymaga pełnej zgodności z renderowaniem przeglądarki, na przykład flexbox, grid lub czcionek internetowych, zainstaluj renderer Artisan i zamiast tego wywołaj writeHtmlChrome(). Ta metoda zachowuje możliwość zaznaczania tekstu.

Z poziomu kontrolera frameworka

Aplikacja może już działać w frameworku albo za pośrednictwem serwera. Te same dwa wywołania można przenieść do tego środowiska. Silnik pozostaje ten sam. Zmienia się jedynie sposób podłączenia.

Laravel

Fasada Pdf dla każdego wywołania rozwiązuje nowy dokument. PdfResponse zamienia dokument w odpowiedź do pobrania:

<?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');
    }
}

Zobacz szybki start z Laravelem.

Symfony

Bundle udostępnia usługę PdfFactory. Dodaj podpowiedź typu NextPDF\Symfony\Service\PdfFactory w kontrolerze, zbuduj dokument w ten sam sposób i zwróć go jako odpowiedź HTTP. Zobacz szybki start z Symfony.

Serwer (REST)

Gdy serwer NextPDF jest uruchomiony, wyślij uporządkowaną tablicę operacji metodą POST, a serwer zwróci bajty 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

W przypadku odpowiedzi 200 treścią odpowiedzi jest plik PDF. Zobacz szybki start z Connect.

Następne kroki

Masz teraz plik PDF wygenerowany na trzy sposoby. Skorzystaj z tych stron, aby rozwinąć każdy z nich.

Renderowanie HTML na stronę PDF Pełny przepis na HTML: obsługiwane elementy, model strumieniowania oraz zabezpieczenia.

Wybierz swoją ścieżkę Zdecyduj między rdzeniem, frameworkiem a serwerem oraz który renderer HTML zastosować.

Dokumentacja silnika rdzeniowego Każda metoda Document, parametr i wartość zwracana.

Zbiór przepisów Przepisy nastawione na zadania: stylizacja, tabele, paginacja i nie tylko.