Integracja NextPDF z Laravel

W skrócie

Ten przewodnik pokazuje, jak skonfigurować NextPDF w aplikacji Laravel 12. Przejdziesz przez sześć etapów: instalację pakietu, automatyczne wykrywanie przez Laravel, opublikowanie konfiguracji, rozwiązanie powiązań kontenera, zwrócenie odpowiedzi w protokole Hypertext Transfer Protocol (HTTP) oraz uruchomienie zadania kolejkowanego. Każdy etap prowadzi do szczegółowej dokumentacji danego obszaru.

Instalacja

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

Rozruch i automatyczne wykrywanie

Laravel automatycznie wykrywa dostawcę usług i alias fasady na podstawie bloku composer.jsonextra.laravel pakietu. Nie musisz edytować pliku config/app.php. Mapa autoloadu korzysta z jednego wpisu PSR-4. Prefiks NextPDF\Laravel\ jest mapowany na src/Laravel/ zgodnie z regułą odwzorowania prefiksu na katalog bazowy PSR-4 (PSR-4 §3). Ponieważ dostawca jest odroczony, uruchamia się dopiero przy pierwszym rozwiązaniu jednego z wpisów provides(). Szczegóły mechanizmu wykrywania znajdziesz na stronie /integrations/laravel/boot-and-discovery/.

Powiązania kontenera

Rozwiąż kontrakt dokumentu z kontenera. Powiązany identyfikator jest rozwiązywany do zarejestrowanego wpisu (PSR-11 §1.1.2). Powiązanie dokumentu ma charakter fabryki, więc każde rozwiązanie zwraca nowy dokument. Rejestry czcionek i obrazów są singletonami, więc każde rozwiązanie zwraca tę samą współdzieloną instancję. Pełną tabelę czasów życia powiązań znajdziesz na stronach /integrations/laravel/overview/ oraz /integrations/laravel/boot-and-discovery/.

<?php

declare(strict_types=1);

use NextPDF\Contracts\PdfDocumentInterface;

$document = app(PdfDocumentInterface::class);
$document->addPage();
$document->cell(0, 10, 'Wired through the container', newLine: true);

Publikowanie konfiguracji

php artisan vendor:publish --tag=nextpdf-config

To polecenie zapisuje plik config/nextpdf.php. Dokumentacja konfiguracji na stronie /integrations/laravel/configuration/ opisuje każdy klucz, odpowiadającą mu zmienną środowiskową oraz wartość domyślną.

Test dymny dostawcy usług/pakietu

Pakiet zawiera zestaw testów oparty na Testbench, który sprawdza dostawcę kompleksowo. Dodaj ten minimalny test dymny do aplikacji korzystającej z pakietu:

<?php

declare(strict_types=1);

namespace Tests\Feature;

use NextPDF\Contracts\FontRegistryInterface;
use NextPDF\Contracts\PdfDocumentInterface;
use NextPDF\Typography\FontRegistry;
use Tests\TestCase;

final class NextPdfIntegrationTest extends TestCase
{
    public function test_document_is_factory_bound(): void
    {
        $a = app(PdfDocumentInterface::class);
        $b = app(PdfDocumentInterface::class);

        self::assertNotSame($a, $b);
    }

    public function test_font_registry_is_singleton_and_locked(): void
    {
        $registry = app(FontRegistryInterface::class);

        self::assertInstanceOf(FontRegistry::class, $registry);
        self::assertTrue($registry->isLocked());
    }
}

Te dwie asercje odpowiadają jednorazowym kontrolom zgodności pakietu w EInvoiceServiceProviderIntegrationTest. Potwierdzają, że dokument jest powiązany jako fabryka, a rejestr czcionek jest zablokowanym singletonem.

Punkty wejścia publicznego API

Punkt wejścia	Przeznaczenie	Dokumentacja
`NextPDF\Laravel\Facades\Pdf`	Statyczny proxy dla nowego dokumentu	/integrations/laravel/quickstart/
`app(NextPDF\Contracts\PdfDocumentInterface::class)`	Dokument rozwiązany przez kontener	/integrations/laravel/production-usage/
`NextPDF\Laravel\Http\PdfResponse`	Odpowiedzi HTTP w trybie inline, pobierania i strumieniowania	/integrations/laravel/security-and-operations/
`NextPDF\Laravel\Jobs\GeneratePdfJob`	Generowanie w kolejce	/integrations/laravel/production-usage/

Przykład kodu — produkcja

Pełny kontroler na stronie /integrations/laravel/production-usage/ pokazuje wstrzykiwanie zależności i obsługę błędów. Ta sama strona opisuje zadanie kolejkowane oraz wywołania zwrotne uruchamiane przy powodzeniu i niepowodzeniu.

Przypadki brzegowe i pułapki

Rozwiązuj PdfDocumentInterface, a nie konkretny Document, aby powiązanie pozostało testowalne i wymienne.
SignerInterface i TsaClient są rozwiązywane do null do czasu skonfigurowania. Zawsze sprawdzaj, czy zwrócona wartość to null.
Kontrakty e-faktur wymagają nextpdf/premium. Są powiązane, ale bez tego pakietu zgłaszają błąd przy pierwszej próbie rozwiązania.

Wydajność

Pełna integracja nie dodaje kosztu rozruchu, ponieważ dostawca jest odroczony. Koszty konstrukcji przy pierwszym rozwiązaniu oraz koszty rozgrzewania czcionek są opisane na stronie /integrations/laravel/boot-and-discovery/.

Uwagi dotyczące bezpieczeństwa

PdfResponse stosuje ustalony zestaw nagłówków Open Worldwide Application Security Project (OWASP). GeneratePdfJob weryfikuje swoją ścieżkę wyjściową w procesie roboczym. Model zagrożeń znajdziesz na stronie /integrations/laravel/security-and-operations/.

Zgodność

Twierdzenie	Źródło	Klauzula	reference_id
Powiązany identyfikator jest rozwiązywany do zarejestrowanego wpisu	PSR-11 Container	§1.1.2
Prefiks PSR-4 jest mapowany na katalog bazowy	PSR-4 Autoloader	§3

Kontekst komercyjny

Po zainstalowaniu nextpdf/premium kontrakty podpisywania, PDF/A oraz e-faktur integrują się przez tego samego dostawcę. Opisany tutaj pakiet Core nie wymaga żadnych zmian w kodzie, aby obsłużyć tę opcjonalną funkcjonalność Enterprise. Zobacz https://nextpdf.dev/get-license/?intent=laravel-signing.

Zobacz także

/integrations/laravel/overview/ — architektura i tabela powiązań
/integrations/laravel/install/ — instalacja i opcjonalne rozszerzenia
/integrations/laravel/quickstart/ — pierwszy uruchamialny przykład
/integrations/laravel/production-usage/ — wstrzykiwanie zależności, obsługa błędów i kolejka
/integrations/laravel/boot-and-discovery/ — wykrywanie i czasy życia