Uruchamianie i wykrywanie NextPDF Artisan

W skrócie

Artisan jest zwykłą biblioteką zgodną z PHP Standard Recommendation 4 (PSR-4). Nie ma dostawcy usług, pakietu (bundle) ani manifestu automatycznego wykrywania frameworka. Uruchamia się, gdy tylko jego klasy stają się dostępne dla automatycznego ładowania. Wykrywanie sprowadza się do mapy PSR-4 obsługiwanej przez Composer i niczego więcej.

Jak działa wykrywanie

Plik composer.json pakietu deklaruje dwa katalogi główne PSR-4: NextPDF\Artisan\ → src/Artisan/ oraz NextPDF\Parser\ → src/Parser/. Nie zawiera extra.laravel, klasy pakietu (bundle) Symfony ani rejestratora CodeIgniter. W trakcie rozruchu nic nie jest skanowane, rejestrowane ani podłączane.

Punkt integracji znajduje się w nextpdf/core. Document (poprzez cechę HasTextOutput) udostępnia writeHtmlChrome(), które w czasie wykonywania sprawdza class_exists() dla NextPDF\Parser\PdfReader oraz NextPDF\Artisan\PageImporter. Gdy mechanizm automatycznego ładowania może rozwiązać obie klasy, ścieżka Chrome jest dostępna. Gdy nie może, core zgłasza wyjątek układu zamiast kończyć działanie błędem krytycznym. Wykrywanie sprowadza się więc do jednego pytania: czy klasy Artisan są w mechanizmie automatycznego ładowania? Odpowiada na nie Composer; żadna maszyneria frameworka nie bierze w tym udziału.

Jest to celowe. Most jest funkcją, po którą core sięga przez granicę pakietu, a nie usługą zarządzaną przez framework. Artisan można używać tak samo w Laravel, Symfony, CodeIgniter, skrypcie wiersza poleceń (CLI) lub procesie roboczym kolejki, ponieważ żaden z tych hostów nie jest wymagany.

Sekwencja rozruchu

Diagram

Artisan nie ma jądra rozruchowego, rejestracji poleceń ani fazy odroczonego dostawcy. Pierwsze wywołanie writeHtmlChrome() jest jedynym wejściem do cyklu życia.

Powiązania kontenera

Artisan nie ma kontenera wstrzykiwania zależności (DI) i nie rejestruje żadnych powiązań. Komponenty są zwykłymi obiektami wstrzykiwanymi przez konstruktor: utwórz ChromeRendererConfig, przekaż go do ChromeHtmlRenderer i opcjonalnie wstrzyknij rejestrator PSR-3 oraz niestandardowy HtmlSecurityPolicyInterface. W kontenerze hosta samodzielnie zarejestruj ChromeHtmlRenderer jako singleton; zobacz przykład na stronie /integrations/artisan/production-usage/.

Rozwiązywanie usług bez kontenera

Niektóre funkcje NextPDF, w tym kontrakty e-faktur w wersji Premium, są zwykle rozwiązywane przez kontener frameworka. Artisan działa również w środowiskach bez kontenera, takich jak narzędzia CLI, samodzielne skrypty i niestandardowe mechanizmy uruchamiające, dlatego dostarcza EInvoiceServiceFactory:

Metoda	Zwraca	Kiedy null
makeEmbedder()	EmbedderInterface (Pro)	Poziom Pro nie jest zainstalowany
makeValidator()	ValidatorInterface (Enterprise)	Poziom Enterprise nie jest zainstalowany
makeDefaultProfile()	ProfileInterface (EN16931, Pro)	Poziom Pro nie jest zainstalowany
makeSchematronRunner()	SchematronRunnerInterface (Enterprise)	Poziom Enterprise nie jest zainstalowany

Każde wywołanie zwraca nową instancję. To zachowanie jednorazowego użycia ma znaczenie, ponieważ operacje osadzania i walidacji mają zmienny kontekst parsowania Extensible Markup Language (XML) i nie mogą współdzielić stanu. Fabryka jest ułatwieniem dla rzadkiego przypadku braku kontenera, a nie lokalizatorem usług. Preferowanym wzorcem nadal jest komponowanie obiektów podczas konstruowania i przekazywanie ich jako argumentów konstruktora. Zwracanie null, gdy danego poziomu nie ma, odzwierciedla działanie pakietów opakowujących przeznaczonych dla frameworków, dzięki czemu ten sam kod wywołujący działa zarówno z wersją Premium, jak i bez niej. Źródło: src/Artisan/EInvoiceServiceFactory.php; testy integracyjne w tests/Integration/Artisan/EInvoiceServiceFactoryIntegrationTest.php.

Kolejność rozwiązywania konfiguracji

Nie ma kaskady plików konfiguracyjnych. Konfiguracja jest dokładnie tym, co przekażesz do ChromeRendererConfig:

1. Argumenty konstruktora, które przekażesz jawnie, lub
2. ChromeRendererConfig::fromArray() z tablicy dostarczonej przez host (klucze w notacji snake_case; nieustawione klucze przyjmują wartości domyślne konstruktora; chrome_binary ma zastosowanie tylko wtedy, gdy jest niepustym ciągiem znaków).

Rozwiązana konfiguracja pozostaje niezmienna przez cały czas życia mechanizmu renderowania. Wszystkie klucze opisano na stronie /integrations/artisan/configuration/.

Diagnostyka

• „Czy most jest wykrywalny?” — jeśli class_exists(\NextPDF\Artisan\PageImporter::class) ma wartość true, mechanizm automatycznego ładowania narzędzia Composer może ją znaleźć, a core użyje ścieżki Chrome.
• „Czy się uruchomił?” — nie ma fazy rozruchu, która mogłaby zakończyć się niepowodzeniem; brakująca zależność ujawnia się przy pierwszym wywołaniu writeHtmlChrome() jako typowany wyjątek, opisany na /integrations/artisan/troubleshooting/.
• Sprawdzenie wersji Premium bez kontenera — EInvoiceServiceFactory::makeEmbedder() === null oznacza, że poziom Pro nie jest zainstalowany; nie wpływa to na ścieżkę renderowania open source.

Zobacz też

• /integrations/artisan/integration/
• /integrations/artisan/overview/
• /integrations/artisan/configuration/
• /integrations/artisan/production-usage/
• /integrations/artisan/troubleshooting/