Rozruch i automatyczne wykrywanie NextPDF w Laravel

W skrócie

Laravel automatycznie wykrywa NextPdfServiceProvider na podstawie pliku composer.json pakietu. Dostawca rejestruje odroczone powiązania kontenera, a w kontekście konsoli publikuje plik konfiguracyjny. Ta strona wyjaśnia mechanizm wykrywania oraz cykl życia każdego powiązania.

Instalacja

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

Jak działa automatyczne wykrywanie w Laravel

Pakiet deklaruje własnego dostawcę i alias fasady w bloku extra.laravel swojego pliku composer.json:

resource: composer.json (extra.laravel)

{
  "extra": {
    "laravel": {
      "providers": [
        "NextPDF\\Laravel\\NextPdfServiceProvider"
      ],
      "aliases": {
        "Pdf": "NextPDF\\Laravel\\Facades\\Pdf"
      }
    }
  }
}

Po uruchomieniu polecenia composer require Laravel odczytuje ten blok, a następnie rejestruje dostawcę i alias. Nie trzeba ręcznie edytować pliku config/app.php ani bootstrap/providers.php. Tablica extra.laravel.providers odpowiada za automatyczną rejestrację dostawców usług, a extra.laravel.aliases za automatyczną rejestrację aliasów fasad (przewodnik po tworzeniu pakietów Laravel 12, https://laravel.com/docs/12.x/packages, pobrano 2026-05-18).

Sekwencja rozruchu

NextPdfServiceProvider implementuje interfejs DeferrableProvider oraz standardowy cykl życia oparty na register() / boot().

1. register() scala konfigurację pakietu pod kluczem nextpdf. Następnie powiązuje wpisy kontenera: rejestr czcionek, rejestr obrazów, fabrykę dokumentów, klienta protokołu Hypertext Transfer Protocol (HTTP) zgodnego z PHP Standards Recommendation 18 (PSR-18), klienta znaczników czasu, podpisującego, dokument oraz kontrakty e-faktur. Każde powiązanie jest domknięciem, więc na tym etapie nie powstają żadne kosztowne obiekty.
2. boot() sprawdza, czy rozszerzenia PHP mbstring i zlib są załadowane. Rejestruje publikowalną konfigurację pod znacznikiem nextpdf-config tylko wtedy, gdy runningInConsole() zwraca wartość true.

Ponieważ dostawca jest odroczony, register() wykonuje się dopiero wtedy, gdy rozwiązywany jest jeden z wpisów zwracanych przez provides(). Rozwiązanie niepowiązanego klucza kontenera nie uruchamia NextPDF.

Powiązania kontenera i czasy życia

PHP Standards Recommendation 11 (PSR-11) dopuszcza, aby dwa kolejne wywołania get() z tym samym identyfikatorem zwracały różne wartości w zależności od strategii powiązania (PSR-11 §1.1.2). Dostawca celowo opiera się na tym zachowaniu:

Klucz powiązania	Czas życia	Uwagi
FontRegistryInterface (+ alias FontRegistry)	singleton, zablokowany po rozgrzewce	Rozgrzewany na podstawie preload_fonts; po zablokowaniu żadne żądanie nie może go zmienić
ImageRegistry	singleton	Ograniczona pamięć podręczna typu least recently used (LRU), której rozmiar ustala image_cache_mb; niezablokowana
DocumentFactoryInterface (+ alias DocumentFactory)	singleton	Bezstanowy; współdzieli oba rejestry
Psr\Http\Client\ClientInterface	singleton	Klient uwzględniający ryzyko ataków typu request forgery, opakowujący klienta curl; tworzony z tsa.*
TsaClient	scoped	null, gdy tsa.url ma pustą wartość
SignerInterface	factory	null, gdy podpisywanie jest wyłączone lub certyfikat ma pustą wartość
PdfDocumentInterface (+ alias nextpdf)	factory	Nowy obiekt NextPDF\Core\Document przy każdym rozwiązaniu, z zastosowanymi domyślnymi metadanymi
EmbedderInterface, ValidatorInterface, ProfileInterface, SchematronRunnerInterface	factory	Rozwiązują się do konkretnych implementacji Premium; bez nextpdf/premium błąd pojawia się przy pierwszym rozwiązaniu

Powiązanie dokumentu stosuje do każdego nowego dokumentu defaults.creator, defaults.language oraz defaults.author, gdy ta wartość nie jest pusta. Gdy pdfa nie jest null, włącza PDF/A (Premium). Gdy sekcja artisan jest obecna i istnieje klasa fabryki przeglądarki Chrome, stosuje konfigurację silnika renderującego Chrome.

Metoda kontenera has() przyjmuje pojedynczy identyfikator tekstowy (PSR-11 §1.1.2). Kontrakty e-faktur są powiązane, więc has() zwraca dla nich true nawet wtedy, gdy Premium nie jest obecny. Brak konkretnej implementacji powoduje błąd dopiero podczas konstrukcji.

Wyłączanie automatycznego wykrywania

Dodaj pakiet do tablicy dont-discover aplikacji, a następnie zarejestruj dostawcę ręcznie:

resource: application composer.json

{
  "extra": {
    "laravel": {
      "dont-discover": ["nextpdf/laravel"]
    }
  }
}

resource: bootstrap/providers.php

<?php

declare(strict_types=1);

return [
    App\Providers\AppServiceProvider::class,
    NextPDF\Laravel\NextPdfServiceProvider::class,
];

Kolejność rozwiązywania konfiguracji

Dla każdego klucza obowiązuje następująca kolejność rozwiązywania: zmienna środowiskowa → opublikowana wartość config/nextpdf.php → domyślna wartość pakietu scalona w register(). Większość kluczy akceptuje nazwę NEXTPDF_* lub starszą nazwę środowiskową TCPDF_*. Zalecamy NEXTPDF_*.

Diagnostyka

php artisan package:discover --ansi

Wiersz zawierający nextpdf/laravel potwierdza wykrycie. Ponieważ dostawca jest odroczony, same powiązania nie pojawiają się przed pierwszym rozwiązaniem. Właściwym sygnałem powodzenia jest wiersz wykrycia.

Przypadki brzegowe i pułapki

• Rejestracja publikacji konfiguracji odbywa się wyłącznie w kontekście konsoli, więc żądanie obsługiwane tylko przez przeglądarkę nigdy jej nie wyzwala. Uruchom vendor:publish z interfejsu wiersza poleceń (CLI).
• Obok kluczy rejestru, fabryki, klienta HTTP, podpisującego, znacznika czasu i dokumentu, provides() obejmuje cztery klucze kontraktów e-faktur.
• Nowa instalacja może wydawać się nieaktywna aż do pierwszego istotnego rozwiązania. Jest to założenie projektowe odroczonego dostawcy, a nie błąd.

Wydajność

register() ma złożoność O(1), ponieważ tworzy wyłącznie domknięcia. Rozgrzewka rejestru czcionek ma złożoność O(f) względem wstępnie załadowanych czcionek i wykonuje się raz na proces roboczy. Odroczenie dostawcy utrzymuje koszt konstrukcji NextPDF poza ścieżką rozruchu frameworka aż do faktycznego użycia powiązania.

Uwagi dotyczące bezpieczeństwa

Odroczona architektura zawęża powierzchnię ataku podczas rozruchu. Zablokowany rejestr czcionek uniemożliwia jednemu żądaniu zmianę stanu czcionek dla innego w długo działających procesach roboczych. Pełny zakres zagrożeń znajdziesz w /integrations/laravel/security-and-operations/.

Zgodność

Twierdzenie	Źródło	Klauzula	reference_id
Kolejne rozwiązania mogą się różnić w zależności od strategii powiązania	PSR-11 Container	§1.1.2
has() przyjmuje jeden identyfikator tekstowy	PSR-11 Container	§1.1.2

Oficjalna dokumentacja pakietów Laravel 12 potwierdza nazwy kluczy mechanizmu wykrywania Laravel (https://laravel.com/docs/12.x/packages, pobrano 2026-05-18).

Kontekst komercyjny

Konkretne implementacje Premium są rozwiązywane przez te same odroczone klucze powiązań. Ta opcjonalna funkcja Enterprise nie wymaga żadnej zmiany kodu w opisanym tutaj pakiecie Core. Zobacz https://nextpdf.dev/get-license/?intent=laravel-signing.

Zobacz też

• /integrations/laravel/install/ — instalacja i publikacja
• /integrations/laravel/overview/ — architektura pakietu
• /integrations/laravel/integration/ — instrukcja pełnego podłączenia
• /integrations/laravel/configuration/ — wszystkie klucze konfiguracji