Dokumentacja API Laravela

W skrócie

Pakiet nextpdf/laravel łączy niezależny od frameworka rdzeń NextPDF z aplikacją Laravel. Bezpośrednio korzysta się z czterech punktów wejścia: fasady Pdf do krótkich przepływów tworzenia dokumentów, powiązania kontenera PdfDocumentInterface do wstrzykiwanego tworzenia dokumentów, pomocnika PdfResponse do odpowiedzi HTTP z gotowych dokumentów oraz zadania kolejki GeneratePdfJob do generowania poza cyklem obsługi żądania. Dostawca NextPdfServiceProvider rejestruje wszystkie powiązania i jest wykrywany automatycznie, więc ręczna konfiguracja nie jest potrzebna. Konfiguracja w pliku config/nextpdf.php steruje ustawieniami domyślnymi, czcionkami, kolejkami oraz opcjonalnymi funkcjami podpisywania i urzędu znaczników czasu (TSA).

Zacznij tutaj: aby wysłać plik w formacie Portable Document Format (PDF) bezpośrednio z kontrolera, zbuduj dokument i zwróć PdfResponse::download($document, 'file.pdf'). Pierwszy przykład poniżej pokazuje ten przepływ.

Typowe zadania

Poniższe fragmenty kodu obejmują trzy przepływy, po które zwykle sięga się najpierw. Każdy fragment jest zweryfikowany ze źródłem pakietu; dalej znajdują się pełne tabele dla poszczególnych symboli.

Zwróć z kontrolera plik PDF do pobrania. To najczęstsze zadanie:

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

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

Co robi: wstrzykuje nowy dokument, zapisuje jeden wiersz i zwraca odpowiedź typu attachment z nagłówkiem Content-Type: application/pdf oraz nagłówkami bezpieczeństwa Open Worldwide Application Security Project (OWASP). Użyj inline() zamiast download(), aby wyświetlić podgląd w przeglądarce.

Twórz i zapisuj za pomocą fasady Pdf. To najkrótsza droga dla skryptów i krótkich przepływów:

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

Co robi: fasada rozwiązuje nowy dokument z kontenera, dodaje jedną komórkę i zapisuje ukończony plik PDF na dysku.

Wygeneruj plik PDF poza wątkiem żądania za pomocą GeneratePdfJob:

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

Co robi: umieszcza generowanie w kolejce dla procesu roboczego. Domknięcie budujące otrzymuje dokument rozwiązany z kontenera i go zwraca. Zadanie waliduje ścieżkę wyjściową .pdf przed zapisem. Nazwa kolejki, limit czasu i połączenie pochodzą z config('nextpdf.queue.*').

Fasada

Fasada Pdf statycznie deleguje wywołania do nowego rdzeniowego obiektu Document. Używaj jej w krótkich przepływach kontrolera, gdy styl statyczny jest czytelny. Każdy wiersz wymienia jedną metodę dokumentu udostępnianą przez fasadę.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
NextPDF\Laravel\Facades\Pdf	brak; statyczny akcesor fasady rozwiązuje NextPDF\Contracts\PdfDocumentInterface	Laravel rozwiązuje bieżące powiązanie kontenera dla interfejsu dokumentu.	Bazowy płynny interfejs API rdzeniowego dokumentu.	Błąd powiązania kontenera Laravela, jeśli dostawca nie jest zarejestrowany.	Używaj jej w krótkich przepływach kontrolera. W usługach i zadaniach preferuj wstrzykiwanie przez konstruktor.
Pdf::setTitle(string $title)	title: tytuł dokumentu.	Zastępuje każdy istniejący tytuł.	static	Błędy walidacji rdzenia lub błędy podczas zapisu.	Deleguje do rdzeniowego obiektu Document.
Pdf::setAuthor(string $author)	author: metadane autora dokumentu.	Zastępuje każdego poprzedniego autora.	static	Błędy walidacji metadanych rdzenia.	W przypadku metadanych obejmujących całą aplikację preferuj skonfigurowane wartości domyślne.
Pdf::addPage(?PageSize $size = null, Orientation $orientation = Portrait)	size: opcjonalny rozmiar strony; orientation: domyślnie Portrait.	Używa skonfigurowanego lub domyślnego rozmiaru strony, jeśli pominięto size.	static	Błędy walidacji strony rdzenia.	Użyj jawnego PageSize, gdy rozmiar wyniku ma znaczenie.
Pdf::setFont(string $family, string $style = '', float $size = 12.0)	Rodzina czcionek, styl i rozmiar w punktach.	Używa pustego stylu i rozmiaru 12 pt.	static	Błędy rejestru czcionek lub kodowania.	Wstępnie załaduj produkcyjne czcionki przez nextpdf.preload_fonts, gdy opóźnienie ma znaczenie.
Pdf::cell(float $width, float $height, string $text = '', bool $border = false, bool $newLine = false, Alignment $align = Left)	Szerokość i wysokość komórki, tekst, flaga obramowania, flaga łamania wiersza oraz wyrównanie.	Używa pustego tekstu, bez obramowania, bez łamania wiersza i z wyrównaniem do lewej.	static	Błędy układu lub kodowania tekstu.	Używaj do prostego wyniku o stałym układzie.
Pdf::multiCell(float $width, float $height, string $text, bool $border = false, Alignment $align = Left)	Szerokość komórki, wysokość wiersza, tekst, flaga obramowania, wyrównanie.	Bez obramowania i z wyrównaniem do lewej.	static	Błędy układu lub kodowania tekstu.	Używaj, gdy tekst ma być zawijany w obrębie stałej szerokości.
Pdf::writeHtml(string $html)	html: fragment HTML.	Renderuje na bieżącej stronie i tworzy stronę w razie potrzeby.	static	Błędy renderowania HTML w rdzeniu.	Zastosuj zasady dotyczące rozmiaru danych wejściowych i zasobów przed przyjęciem niezaufanego kodu HTML.
Pdf::image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null)	Ścieżka pliku i opcjonalny prostokąt umieszczenia.	Pozwala rdzeniowemu dokumentowi wybrać bieżącą pozycję i natywny rozmiar obrazu, jeśli pominięto współrzędne.	static	Błędy dekodowania obrazu, ścieżki lub układu.	Sprawdź zasady dotyczące źródła obrazu przed przyjęciem ścieżek podanych przez użytkownika.
Pdf::output(?string $filename = null, OutputDestination $dest = Inline)	filename: opcjonalna nazwa; dest: cel wyjściowy.	Używa wyjścia wbudowanego, gdy cel jest pominięty.	string	Błędy serializacji rdzenia.	W odpowiedziach HTTP Laravela preferuj PdfResponse.
Pdf::save(string $path)	path: cel w systemie plików.	Zapisuje ukończony plik PDF na dysku.	void	Błędy systemu plików lub zapisu w rdzeniu.	Sprawdzaj katalogi wyjściowe w kodzie aplikacji.
Pdf::getPdfData()	brak.	Materializuje bajty PDF w pamięci.	string	Błędy serializacji rdzenia.	Używaj, gdy inny obiekt frameworka musi przejąć treść odpowiedzi.

Dostawca usług i powiązania

Skorzystaj z tej tabeli, gdy trzeba bezpośrednio rozwiązać lub nadpisać wpis kontenera, na przykład wstrzyknąć DocumentFactoryInterface do usługi albo sprawdzić, jakie usługi odracza provides().

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
NextPdfServiceProvider::register()	brak.	Scala config/nextpdf.php; rejestruje rejestry, fabrykę dokumentów, powiązanie dokumentu, klienta HTTP, klienta TSA, podpisywacza oraz opcjonalne kontrakty e-faktur.	void	Błędy kontenera lub rozwiązywania opcjonalnych klas podczas korzystania z funkcji.	FontRegistryInterface i ImageRegistry są współdzielone; dokumenty są zawsze nowe.
NextPdfServiceProvider::boot()	brak.	Waliduje wymagane rozszerzenia PHP i publikuje nextpdf-config podczas pracy w konsoli.	void	RuntimeException, jeśli wymagane rozszerzenie jest niedostępne.	Wymagane rozszerzenia to mbstring i zlib.
NextPdfServiceProvider::provides()	brak.	Zgłasza identyfikatory odroczonych usług.	array<string>	brak oczekiwanych błędów.	Obejmuje PdfDocumentInterface, DocumentFactoryInterface, FontRegistryInterface, SignerInterface, TsaClient, ClientInterface oraz nextpdf.
PdfDocumentInterface / nextpdf	rozwiązywane z kontenera Laravela.	Tworzy jednorazowy Document za pomocą DocumentFactoryInterface, a następnie stosuje skonfigurowane wartości domyślne i opcjonalne ustawienia PDF/A lub Artisana.	NextPDF\Core\Document	Błędy opcjonalnych rozszerzeń, gdy są skonfigurowane, lecz niedostępne.	Rozwiązuj nowy dokument dla każdego żądania lub zadania.
DocumentFactoryInterface	rozwiązywane z kontenera Laravela.	Fabryka typu singleton, która współdzieli rejestry czcionek i obrazów o czasie życia procesu.	DocumentFactoryInterface	Błędy konfiguracji rejestru.	Używaj do jawnego wstrzykiwania zależności.
SignerInterface	rozwiązywane z kontenera Laravela.	Zwraca null, chyba że ustawiono nextpdf.signature.enabled i skonfigurowano ścieżki certyfikatów.	`SignerInterface	null`	Błędy wczytywania certyfikatu lub walidacji na poziomie podpisu.

Konfiguracja

Skorzystaj z tej tabeli, aby wyszukać klucze nextpdf.* dostępne w środowisku uruchomieniowym i odczytywane przez powiązania. Pełna dokumentacja poszczególnych kluczy, w tym zmiennych środowiskowych i wartości domyślnych, znajduje się pod adresem /integrations/laravel/configuration/.

Klucz	Typ	Zachowanie domyślne	Uwagi
nextpdf.fonts_path	string	Używa czcionek z zasobów Laravela, jeśli pominięto.	Katalog na czcionki niestandardowe i wstępne ładowanie.
nextpdf.cache_path	string	Ścieżka pamięci podręcznej aplikacji.	Zadbaj, aby była zapisywalna dla procesu roboczego PHP.
nextpdf.preload_fonts	list<string>	Pusta lista.	Czcionki są wstępnie ładowane podczas tworzenia rejestru, po czym rejestr jest blokowany.
nextpdf.image_cache_mb	int	Ograniczony rozmiar pamięci podręcznej obrazów.	Ogranicza pamięć podręczną obrazów o czasie życia procesu.
nextpdf.defaults.*	array	Twórca NextPDF, język en, opcjonalne domyślne wartości autora i układu.	Stosowane do każdego nowego dokumentu.
nextpdf.artisan.*	array	Mechanizm renderujący Chrome jest wyłączony, chyba że zostanie zainstalowany i skonfigurowany.	Mapowane na ChromeRendererConfig::fromArray().
nextpdf.signature.*	array	Podpisywanie domyślnie wyłączone.	Certyfikat, klucz prywatny, hasło, dodatkowe certyfikaty oraz poziom podpisu.
nextpdf.tsa.*	array	TSA wyłączony, gdy adres Uniform Resource Locator (URL) jest pusty.	Obsługuje poświadczenia, pliki wzajemnego Transport Layer Security (mTLS), limit czasu, przypięcia klucza publicznego oraz zasady HTTP.
nextpdf.ocsp_cache.*	array	Pamięć podręczna Online Certificate Status Protocol (OCSP) włączona ze skonfigurowanym TTL.	Używana przez przepływy walidacji podpisu, gdy jest dostępna.

Odpowiedzi HTTP

Skorzystaj z tej tabeli, gdy zwracasz ukończony dokument przez HTTP i musisz wybrać wyświetlanie wbudowane, pobieranie jako załącznik lub wyjście strumieniowane.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
PdfResponse::inline(Document $document, string $filename = 'document.pdf')	document: zbudowany dokument; filename: nazwa pliku w Content-Disposition.	Normalizuje puste nazwy plików do document.pdf.	Illuminate\Http\Response	Błędy serializacji rdzenia lub konstruowania odpowiedzi.	Ustawia typ zawartości PDF oraz nagłówki zabezpieczające.
PdfResponse::download(Document $document, string $filename = 'document.pdf')	Tak samo jak inline; dyspozycją jest załącznik.	Zwraca odpowiedź pobieraną przez przeglądarkę.	Illuminate\Http\Response	Tak samo jak inline.	Używaj do jawnego pobierania plików.
PdfResponse::streamInline(Document $document, string $filename = 'document.pdf')	Tak samo jak inline.	Materializuje bajty PDF, a następnie emituje fragmenty po 64 KB.	Symfony\Component\HttpFoundation\StreamedResponse	Tak samo jak inline.	To strumieniowane wyjście HTTP, a nie renderowanie bez kopiowania.
PdfResponse::streamDownload(Document $document, string $filename = 'document.pdf')	Tak samo jak streamInline; dyspozycją jest załącznik.	Odpowiedź pobierania strumieniowego.	StreamedResponse	Tak samo jak streamInline.	Wymuszaj limity rozmiaru danych wejściowych i wyjściowych przed renderowaniem.

Zadanie kolejki

Skorzystaj z tej tabeli, gdy przenosisz generowanie poza wątek obsługi żądania. Obejmuje konstrukcję, wysyłanie oraz wywołania zwrotne sukcesu lub niepowodzenia dla GeneratePdfJob.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
new GeneratePdfJob(string $outputPath, callable $builder, ?callable $onSuccess = null, ?callable $onFailure = null)	outputPath: docelowy .pdf; builder: otrzymuje PdfDocumentInterface; wywołania zwrotne są opcjonalne.	Nazwa kolejki, limit czasu i połączenie są odczytywane z config('nextpdf.queue.*').	Instancja zadania.	Błędy serializacji, jeśli budowniczego lub wywołań zwrotnych nie można zserializować.	Budowniczy musi zwrócić skonfigurowany dokument.
GeneratePdfJob::handle()	brak.	Rozwiązuje PdfDocumentInterface, stosuje budowniczego, waliduje ścieżkę wyjściową, a następnie zapisuje.	void	InvalidArgumentException dla niebezpiecznych ścieżek wyjściowych; błędy zapisu w rdzeniu.	Odrzuca opakowania strumieni, bajty null, segmenty .. oraz ścieżki inne niż .pdf.
GeneratePdfJob::failed(Throwable $exception)	exception: przyczyna niepowodzenia.	Wywołuje skonfigurowane wywołanie zwrotne niepowodzenia, jeśli jest obecne.	void	Niepowodzenia wywołania zwrotnego.	Zachowaj idempotentność wywołań zwrotnych.
GeneratePdfJob::then(callable $callback)	callback: otrzymuje ścieżkę wyjściową.	Zastępuje wywołanie zwrotne sukcesu.	self	Błędy serializowalnego domknięcia.	Płynny pomocnik do konfiguracji wysyłania.
GeneratePdfJob::catch(callable $callback)	callback: otrzymuje zgłoszony Throwable.	Zastępuje wywołanie zwrotne niepowodzenia.	self	Błędy serializowalnego domknięcia.	Używaj do powiadamiania lub kompensacyjnego czyszczenia.

Uwagi programistyczne

• PdfResponse zawsze wywołuje getPdfData() przed skonstruowaniem odpowiedzi. Nie działa jako leniwy budowniczy dokumentów.
• Ładunki kolejek mogą zostać zmanipulowane we współdzielonych transportach; ograniczaj ścieżki wyjściowe do katalogu należącego do aplikacji.
• Używaj nowego dokumentu dla każdego żądania lub zadania. Nie używaj ponownie tego samego dokumentu w różnych żądaniach.