Szybki start z NextPDF dla Laravela

W skrócie

W tym samouczku utworzysz w kontrolerze plik w formacie Portable Document Format (PDF), gotowy do pobrania. Następnie przeniesiesz tę samą pracę do kolejkowanego zadania. Każdy fragment kodu odpowiada zachowaniu weryfikowanemu przez zestaw testów pakietu.

Instalacja

composer require nextpdf/laravel
php artisan vendor:publish --tag=nextpdf-config

Przegląd koncepcyjny

Trzy punkty wejścia obejmują niemal każdy przypadek użycia w Laravelu. Fasada pozwala najszybciej rozpocząć pracę. PdfResponse zamienia dokument w odpowiedź Hypertext Transfer Protocol (HTTP). Kolejkowane zadanie przenosi kosztowne generowanie poza wątek żądania, dzięki czemu nie trzeba na nie czekać. Ten samouczek omawia po kolei każdy z punktów wejścia. Wersje produkcyjne dodają obsługę błędów i znajdują się pod adresem /integrations/laravel/production-usage/.

Przykład kodu — szybki start

1. Fasada

Przy każdym wywołaniu fasada pobiera nowy dokument z kontenera. Kontener jest rejestrem usług Laravela. Ten fragment kodu odpowiada zachowaniu weryfikowanemu przez tests/Unit/Laravel/Facades/PdfTest.php.

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

2. Odpowiedź do pobrania z kontrolera

PdfResponse::download() zwraca obiekt Illuminate\Http\Response z nagłówkiem Content-Type: application/pdf, dyspozycją attachment oraz nagłówkami bezpieczeństwa Open Worldwide Application Security Project (OWASP). tests/Unit/Laravel/Http/PdfResponseTest.php sprawdza kod statusu, typ zawartości, prefiks dyspozycji i nagłówki.

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

Aby wyświetlić podgląd bezpośrednio w przeglądarce, zamień download() na inline(). W przypadku dużych dokumentów użyj streamInline() lub streamDownload(). Wysyłają plik PDF w deterministycznych porcjach po 64 KB.

3. Generowanie w kolejce

GeneratePdfJob buduje i zapisuje plik PDF w procesie roboczym kolejki. Domknięcie budujące dokument otrzymuje dokument pobrany z kontenera i zwraca skonfigurowany dokument. tests/Unit/Laravel/Jobs/GeneratePdfJobTest.php potwierdza, że zadanie tworzy plik dokładnie pod wskazaną ścieżką wyjściową.

<?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),
);

Ścieżka wyjściowa musi kończyć się rozszerzeniem .pdf. Zadanie weryfikuje ścieżkę w procesie roboczym przed zapisem.

Przykład kodu — wersja produkcyjna

Wersje produkcyjne dodają jawną obsługę błędów, wywołania zwrotne sukcesu i niepowodzenia w zadaniu oraz typowaną strategię wyjątków. Zostały w pełni udokumentowane pod adresem /integrations/laravel/production-usage/.

Przypadki brzegowe i pułapki

Fasada przy każdym pobraniu zwraca inną instancję dokumentu. Nie buforuj Pdf::getFacadeRoot() pomiędzy logicznymi dokumentami.
Jeśli przekażesz pustą nazwę pliku do dowolnej fabryki PdfResponse, domyślnie przyjmie ona wartość document.pdf. Zestaw testów odpowiedzi weryfikuje tę wartość domyślną.
Nazwy plików spoza zakresu ASCII otrzymują automatycznie parametr RFC 5987 filename*=. Nazwy w ASCII go nie otrzymują.
GeneratePdfJob odrzuca przechodzenie po ścieżkach, opakowania strumieni, bajty zerowe oraz każde rozszerzenie inne niż .pdf. Zgłasza wówczas InvalidArgumentException w procesie roboczym.

Wydajność

Jednostronicowy dokument generuje się z dużym zapasem względem budżetu czasu rzeczywistego na stronę podanego w nagłówku front matter. Przeniesienie generowania do GeneratePdfJob całkowicie usuwa z żądania HTTP czas budowania pliku PDF. Żądanie zwraca wynik, gdy tylko zadanie zostanie wysłane do kolejki.

Uwagi dotyczące bezpieczeństwa

Fabryki PdfResponse stosują stały zestaw nagłówków OWASP. Oczyszczają również nazwę pobieranego pliku. Kolejkowane zadanie weryfikuje ścieżkę wyjściową. Szczegółowe omówienie zagrożeń jest dostępne pod adresem /integrations/laravel/security-and-operations/.

Zgodność

Tego samouczka nie reguluje żadna norma o charakterze normatywnym. Każdy fragment kodu jest weryfikowany względem kodu źródłowego pakietu oraz odpowiadającego mu testu w katalogu tests/.

Kontekst komercyjny

Podpisywanie dokumentów oraz wyjście PDF/A są dostępne w pakiecie nextpdf/premium jako opcjonalna funkcja Enterprise. Opisany tutaj pakiet Core nie wymaga żadnych zmian w kodzie, aby z nich skorzystać. Zobacz https://nextpdf.dev/get-license/?intent=laravel-signing.

Zobacz także

/integrations/laravel/install/ — instalacja i publikowanie konfiguracji
/integrations/laravel/production-usage/ — kontroler i zadanie połączone za pomocą wstrzykiwania zależności oraz obsługi błędów
/integrations/laravel/configuration/ — klucze konfiguracji używane w tym miejscu
/integrations/laravel/overview/ — architektura i czasy życia powiązań