Instalacja pakietu NextPDF dla Laravel

W skrócie

Zainstaluj nextpdf/laravel za pomocą Composera. Mechanizm automatycznego wykrywania pakietów w Laravel automatycznie rejestruje dostawcę usług. Opublikuj plik konfiguracyjny, jeśli chcesz go edytować. Pakiet sam wykrywa opcjonalne rozszerzenia NextPDF.

Instalacja

composer require nextpdf/laravel

Pakiet deklaruje w pliku composer.json następujące ograniczenia:

Wymaganie	Ograniczenie
PHP	`>=8.4 <9.0`
`laravel/framework`	`^12.0`
`nextpdf/core`	`^3.0 \|\| ^5.2`
`psr/http-client`	`^1.0`

Pakiet jest ładowany automatycznie za pomocą pojedynczego mapowania zgodnego z PHP Standard Recommendation 4 (PSR-4). Prefiks NextPDF\Laravel\ jest mapowany na src/Laravel/. Jest to zgodne z regułą PSR-4 dotyczącą odwzorowania prefiksu na katalog bazowy (PSR-4 §3).

Omówienie koncepcyjne

Po uruchomieniu composer require mechanizm automatycznego wykrywania pakietów w Laravel odczytuje blok extra.laravel w pliku composer.json tego pakietu. Następnie automatycznie rejestruje dostawcę oraz alias fasady, więc nie trzeba ręcznie edytować config/app.php. Blok wygląda następująco:

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

Dokumentacja pakietów Laravel wyjaśnia to zachowanie. Tablica extra.laravel.providers odpowiada za automatyczną rejestrację dostawców usług, a tablica extra.laravel.aliases za automatyczną rejestrację aliasów fasad (przewodnik tworzenia pakietów Laravel 12, https://laravel.com/docs/12.x/packages, pobrano 2026-05-18).

Przykład kodu — szybki start

Użyj tagu nextpdf-config, aby opublikować plik konfiguracyjny. Nazwa tagu jest zdefiniowana w NextPdfServiceProvider::boot().

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

Polecenie zapisuje config/nextpdf.php w aplikacji. Dostawca scala także domyślną konfigurację pakietu pod kluczem nextpdf podczas register(), więc pakiet działa jeszcze przed publikacją. Publikacja sprawia, że plik staje się edytowalny w aplikacji.

Sprawdź, czy Laravel wykrył dostawcę:

php artisan package:discover --ansi

Przykład kodu — środowisko produkcyjne

Przypnij ograniczenie wersji, aby zapewnić powtarzalne wdrożenia. Jawnie wyłącz wykrywanie tylko wtedy, gdy samodzielnie rejestrujesz dostawcę:

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

Gdy wykrywanie jest wyłączone, samodzielnie zarejestruj dostawcę w bootstrap/providers.php:

<?php

declare(strict_types=1);

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

Opcjonalne rozszerzenia

Pakiet wymienia opcjonalne pakiety towarzyszące w sekcji suggest pliku composer.json. Wykrywa zainstalowane pakiety towarzyszące w czasie działania:

Pakiet	Efekt po zainstalowaniu	Punkt wykrywania
`nextpdf/artisan`	Konfiguracja mechanizmu renderowania Hypertext Markup Language (HTML) opartego na Chrome DevTools Protocol (CDP) jest stosowana do powiązania dokumentu, gdy dostępna jest klasa fabryki przeglądarki Chrome	`NextPdfServiceProvider::register()` sprawdza obecność klasy fabryki przeglądarki Chrome
`nextpdf/premium`	Istniejące klucze kontenera są rozwiązywane do konkretnych implementacji kontraktów podpisu PDF Advanced Electronic Signatures (PAdES B-B), archiwizacji PDF/A oraz e-faktury	rozwiązywane leniwie podczas pierwszego rozwiązania przez kontener

Rozszerzenie instaluje się w taki sam sposób:

composer require nextpdf/artisan

Nie jest wymagana żadna dodatkowa konfiguracja połączeń. Dostawca wykrywa rozszerzenie w kolejnym cyklu rejestracji.

Przypadki brzegowe i pułapki

Publikacja jest idempotentna. Nie nadpisuje istniejącego pliku config/nextpdf.php. Dodaj --force, gdy chcesz go celowo nadpisać.
Dostawca jest odroczony, więc do potwierdzenia obecności pakietu wystarczy pomyślne php artisan package:discover. Same powiązania pojawiają się dopiero przy pierwszym rozwiązaniu.
Pakiet obsługuje nextpdf/core zarówno w linii ^3.0, jak i ^5.2. Dopasuj ograniczenie pakietu Core do linii przypiętej w aplikacji. Powierzchnia adaptera Laravel pozostaje taka sama w obu przypadkach.
Plakietka w pliku README oraz composer.json wskazują Apache-2.0. Pakiet zmienił licencję z LGPL-3.0-or-later. Wersje oznaczone tagami sprzed migracji pozostają na poprzedniej licencji (zobacz CHANGELOG.md).

Wydajność

Rozwiązywanie nextpdf/core stanowi główny koszt composer require. Rejestracja dostawcy nie dodaje mierzalnego kosztu rozruchu, ponieważ wszystkie powiązania są odroczonymi domknięciami. Szczegóły kosztu konstrukcji przy pierwszym rozwiązaniu opisuje /integrations/laravel/boot-and-discovery/.

Uwagi dotyczące bezpieczeństwa

Instaluj z kanonicznego pakietu Packagist nextpdf/laravel. Pakiet zawiera nagłówki REUSE Software Package Data Exchange (SPDX) oraz plik Apache-2.0 NOTICE. Przypnij ograniczenie w composer.json i zatwierdź composer.lock, aby wdrożone procesy robocze rozwiązywały zweryfikowane drzewo zależności.

Zgodność

Deklaracja	Źródło	Klauzula	reference_id
Prefiks PSR-4 jest odwzorowywany na katalog bazowy	PSR-4 Autoloader	§3

Nazwy kluczy automatycznego wykrywania w Laravel zostały zweryfikowane na podstawie oficjalnej dokumentacji tworzenia pakietów Laravel 12 (https://laravel.com/docs/12.x/packages, pobrano 2026-05-18).

Kontekst komercyjny

nextpdf/premium dodaje konkretne implementacje podpisywania, PDF/A oraz e-faktury jako opcjonalną funkcję Enterprise. Można je wdrożyć bez zmiany pakietu Core opisanego w tym dokumencie. Zobacz https://nextpdf.dev/get-license/?intent=laravel-signing.

Zobacz także

/integrations/laravel/overview/ — architektura pakietu i tabela powiązań
/integrations/laravel/quickstart/ — pierwszy działający kontroler
/integrations/laravel/configuration/ — objaśnienie każdego klucza konfiguracji
/integrations/laravel/boot-and-discovery/ — wewnętrzne mechanizmy wykrywania i cykle życia powiązań