FAQ NextPDF

W skrócie

Ta strona odpowiada na pytania, które pojawiają się jako pierwsze, gdy oceniasz NextPDF lub rozpoczynasz nowy projekt. Każda odpowiedź jest krótka i odsyła do strony, która omawia ją w pełni. NextPDF to silnik PHP 8.4, który generuje i inspekcjonuje dokumenty Portable Document Format (PDF) 2.0, czyli formatu pliku zdefiniowanego przez ISO 32000-2.

Jeśli zaczynasz całkiem od zera, przeczytaj najpierw Pierwsze kroki, a potem wróć tutaj po szczegóły.

Pierwsze kroki

Której edycji potrzebuję: Core, Pro czy Enterprise?

Zacznij od Core. Otwartoźródłowy rdzeń (nextpdf/core) generuje wyjście PDF, renderuje obsługiwany HTML do plików PDF oraz inspekcjonuje pliki PDF na licencji Apache-2.0 i bez opłat. Core wytwarza już podpisy CMS SignedData dla bazowych poziomów PDF Advanced Electronic Signatures (PAdES) B-B i B-T. Wybierz Pro, gdy potrzebujesz zaawansowanego generowania i operacji na dokumentach, wyjścia faktur elektronicznych (Factur-X / ZUGFeRD) albo zaawansowanych przepływów podpisywania, takich jak podpisywanie zdalne, chmurowe oparte na KMS oraz sekwencyjne. Wybierz Enterprise, gdy potrzebujesz przepływów autorskich archiwizacji PDF/A, długoterminowych poziomów PAdES (B-LT / B-LTA) z Document Security Store i znacznikami czasu dokumentu, podpisywania wspieranego sprzętowo przez moduł bezpieczeństwa sprzętowego (HSM) albo kwalifikowanych podpisów elektronicznych. Pro i Enterprise to dwie licencjonowane edycje NextPDF Premium, płatnej linii; zobacz Wybierz swoją ścieżkę.

Czy to naprawdę Apache-2.0?

Tak, dla rdzenia. nextpdf/core deklaruje "license": "Apache-2.0" i dostarcza pełny tekst Apache License 2.0 w swoim pliku LICENSE. Możesz używać, modyfikować, redystrybuować i komercjalizować rdzeń, z zastrzeżeniem wymogów atrybucji i pliku NOTICE (Apache-2.0 §4). NextPDF Pro oraz NextPDF Enterprise to zastrzeżone edycje komercyjne i nie są objęte tą licencją. Nazwa i logo NextPDF są znakami towarowymi, oddzielnymi od licencji kodu. Zobacz Licencjonowanie produktu.

Jaka jest minimalna wersja PHP?

PHP 8.4. Ograniczenie pakietu to >=8.4 <9.0, więc Composer odmawia instalacji na PHP 8.3 lub niższym, ani na PHP 9. NextPDF celuje w jedno nowoczesne środowisko uruchomieniowe i bezpośrednio korzysta z jego cech językowych. Zobacz Instalacja NextPDF.

Czy potrzebuje zewnętrznego pliku binarnego lub przeglądarki headless?

Nie, nie dla silnika rdzenia. Natywny silnik jest zaimplementowany w PHP i standardowych rozszerzeniach PHP, bez zewnętrznego pliku binarnego PDF i bez obowiązkowej przeglądarki headless: płynne API oraz wbudowany potok HTML writeHtml() działają w ramach procesu, bez przeglądarki i bez wywołania sieciowego. Plik binarny Chrome lub Chromium jest opcjonalny i potrzebny jedynie dla renderera Artisan (writeHtmlChrome()), który instalujesz osobno jako nextpdf/artisan. Mostki Cloudflare i Gotenberg są również opcjonalne i odwołują się do usługi. Zobacz Wybierz swoją ścieżkę.

Których rozszerzeń PHP wymaga?

Plik composer.json rdzenia wymaga standardowych rozszerzeń ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl oraz ext-openssl, które są powszechnie dostępnymi rozszerzeniami PHP; upewnij się, że są zainstalowane i włączone w Twoim środowisku uruchomieniowym. ext-curl stoi za opcjonalnymi przebiegami sieciowymi — znacznikowaniem czasu RFC 3161 i pobieraniem zdalnych zasobów — więc offline’owe generowanie natywne go nie wykorzystuje, lecz Composer i tak wymienia je jako twardy wymóg. Integracje sprawdzają te, których potrzebują, przy starcie i zatrzymują się z czytelnym komunikatem, jeśli któregokolwiek brakuje. Pełna lista znajduje się w pliku composer.json pakietu; zobacz Instalacja NextPDF.

Jak wygenerować mój pierwszy plik PDF?

Zainstaluj rdzeń, a następnie zbuduj dokument za pomocą płynnego API:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$document = Document::createStandalone();
$document->addPage();
$document->setFont('helvetica', 'B', 24);
$document->cell(0, 15, 'Hello, NextPDF!', newLine: true);
$document->save(__DIR__ . '/first.pdf');

Przejdź przez to krok po kroku w Twój pierwszy plik PDF.

Edycje i licencjonowanie

Czy Core ma jakieś ograniczenia funkcji lub znak wodny?

Nie. Core to otwartoźródłowy silnik dla zestawu funkcji Core, bez znaku wodnego i bez ekranu zachęcającego. Dla zestawu funkcji Core — generowanie, inspekcja, szyfrowanie, prymitywy wyjścia PDF/A i PDF/UA oraz podpisywanie B-B/B-T kluczem programowym (bez premiumowych przepływów długoterminowej walidacji i kustodii kluczy) — Core jest kompletny. Znak wodny wersji ewaluacyjnej dotyczy wyłącznie przyznanej licencji ewaluacyjnej Premium, gdzie testujesz pełen zestaw funkcji Pro i Enterprise za usuwalnym oznaczeniem; płatna licencja usuwa je bez żadnej zmiany w kodzie aplikacji. Zobacz Licencjonowanie i aktywacja.

Czy potrzebuję zmian w kodzie, aby przejść na Pro lub Enterprise?

Przeważnie nie. Gdy zainstalujesz nextpdf/premium, integracje frameworków oraz serwer wykrywają go automatycznie i udostępniają dodatkowe możliwości. Większość aplikacji zachowuje te same wysokopoziomowe punkty integracji; niektóre premiumowe przepływy mogą wymagać konfiguracji lub wywołań specyficznych dla funkcji. Aktywujesz podpisaną kopertę licencyjną raz na wdrożenie. Zobacz Licencjonowanie i aktywacja.

Czy mogę używać rdzenia w zamkniętoźródłowym produkcie komercyjnym?

Tak. Apache License 2.0 nie ma ograniczenia niekomercyjnego. Możesz używać rdzenia w zamkniętoźródłowych, płatnych lub wewnętrznych produktach komercyjnych, pod warunkiem że dotrzymasz zobowiązań atrybucji i pliku NOTICE oraz nie potraktujesz licencji kodu jako pozwolenia na używanie marki NextPDF. Zobacz Licencjonowanie produktu oraz Znak towarowy i używanie marki.

Możliwości

Czy potrafi odczytywać i parsować pliki PDF, czy tylko je zapisywać?

Jedno i drugie, z zastrzeżeniem. NextPDF zapisuje pliki PDF, a także je odczytuje: moduł Inspect odczytuje istniejący plik do strukturalnego InspectResult z danymi o złożoności, czcionkach, obrazach i ryzyku, a istniejące dokumenty możesz scalać i dzielić. Inspect jest oznaczony jako eksperymentalny, więc kształt jego wyniku może się zmieniać między wersjami pomocniczymi — używaj go do diagnostyki i bramkowania, a nie jako długowiecznego kontraktu. Zobacz Moduł Inspect.

Czy wytwarza zaznaczalny, przeszukiwalny tekst?

Tak. Zarówno płynne API, jak i wbudowany potok writeHtml() emitują rzeczywistą treść tekstową, a nie zrasteryzowane obrazy, więc wyjście jest zaznaczalne i przeszukiwalne. Renderer Artisan writeHtmlChrome() również utrzymuje tekst zaznaczalnym. Zobacz Twój pierwszy plik PDF.

Jak działa renderowanie HTML i CSS?

Silnik rdzenia zawiera czysto-PHP-owy potok HTML. writeHtml() renderuje fragment HTML z obsługiwanym podzbiorem CSS bezpośrednio na stronę, bez przeglądarki i bez wywołania sieciowego. Gdy układ wymaga pełnej wierności przeglądarki — na przykład flexboksa, grida lub czcionek internetowych — zainstaluj renderer Artisan i wywołaj writeHtmlChrome(). Zanim oprzesz się na jakiejś właściwości, sprawdź macierz wsparcia CSS.

Jak działają czcionki?

Wbudowane aliasy standardowych czcionek, takie jak Helvetica, działają bez żadnej konfiguracji dla prostego tekstu WinAnsi, więc Twój pierwszy dokument nie potrzebuje żadnych plików czcionek. Wbudowane łacińskie czcionki standardowe nadają się do podstawowego tekstu WinAnsi; Symbol i ZapfDingbats używają własnych kodowań; aby renderować inne pisma, rejestrujesz i osadzasz czcionkę, której mapa znaków i ścieżka kształtowania obsługują dane pismo. Zobacz macierz wsparcia czcionek oraz Moduł Font.

Czy obsługuje PDF/A i dostępność (PDF/UA)?

Tak, z wyraźną granicą: wsparcie dla profilu to nie zgodność. Rdzeń dostarcza dyskryminator zgodności oraz prymitywy tagowania — enableTaggedPdf() włącza wyjście struktury tagowanego PDF używane w przepływach PDF/UA, a enablePdfA() wybiera profil wyjścia PDF/A w Core; edycje Premium dodają na wierzchu wyższopoziomowe przepływy autorskie archiwizacji i narzędzia (walidacja, polityka oraz operacje produkcyjne). NextPDF emituje artefakty strukturalne, których wymaga profil; niezależny walidator, taki jak veraPDF, rozstrzyga, czy dany plik faktycznie jest zgodny. Zobacz Zgodność oraz Moduł Accessibility.

Jak podpisać plik PDF?

Rdzeń potrafi wytwarzać podpisy Cryptographic Message Syntax (CMS) SignedData oraz może stosować znaczniki czasu RFC 3161 (poziom B-T), używając obsługiwanych algorytmów z kluczem programowym przez skonfigurowanego dostawcę podpisu. Twój kod zależy od kontraktu SignerInterface, więc to samo wywołanie działa we wszystkich edycjach. Długoterminowe poziomy PAdES B-LT i B-LTA, kustodia kluczy HSM i PKCS#11 oraz podpisy kwalifikowane to możliwości Enterprise; przepływy podpisywania wspierane chmurą i KMS dostarczane są w Pro. Core wytwarza struktury bazowe B-B i B-T. Zobacz Moduł Signing.

Produkcja

Czy jest bezpieczny dla procesów roboczych i wątkowo?

Document jest jednorazowego użytku: gdy zapiszesz jeden, utwórz świeżą instancję dla następnego dokumentu, zamiast go ponownie używać. To czyni go naturalnym dopasowaniem do modelu per żądanie, per zadanie używanego przez PHP-FPM, procesy robocze kolejek i frameworki — każda jednostka pracy buduje własny dokument. Gdy parsujesz lub komponujesz niezaufane wejście, uruchamiaj tę pracę w ograniczonym procesie roboczym i utrzymuj ciasne zabezpieczenia zasobów (maxFiles, maxTotalBytes, maxBytes). Zobacz Moduł Document oraz model zagrożeń silnika.

Czy wyjście jest deterministyczne?

Jest strukturalnie deterministyczne, ale domyślnie nie identyczne bajt po bajcie. Dwa przebiegi na tym samym wejściu wytwarzają strukturalnie równe pliki PDF, ale każdy niesie świeży trailer i /ID dokumentu, więc bajty się różnią. Podpisywanie i znaczniki czasu z założenia dodają dalsze zróżnicowanie per przebieg. Planuj porównania wokół równości strukturalnej albo normalizuj zmienne pola, zamiast oczekiwać identycznych bajtów między przebiegami.

Jak go wdrożyć?

Zatwierdź composer.lock, aby każdy wdrożony proces roboczy rozwiązywał tę samą wersję silnika, a następnie wdróż tak, jak dowolną bibliotekę PHP — generowanie natywne nie potrzebuje demona, przeglądarki ani sieci; znacznikowanie czasu (B-T), zdalne zasoby lub opcjonalny mostek przeglądarki wymagają skonfigurowanego dostępu sieciowego. Jeśli usługi spoza PHP potrzebują silnika, uruchom NextPDF Server, który udostępnia go przez Model Context Protocol (MCP), REST oraz gRPC. Dla Premium umieść podpisaną kopertę licencyjną tam, gdzie ładuje ją wdrożenie, i wykonaj jednorazowy krok aktywacji; buforowany stan licencji oznacza, że normalne przetwarzanie nie potrzebuje usługi licencyjnej, więc wdrożenia odizolowane od sieci (air-gapped) są obsługiwane. Zobacz Instalacja NextPDF oraz Licencjonowanie i aktywacja.

Gdzie zgłaszam awarię, gdy coś pójdzie nie tak?

NextPDF raportuje błędy według klasy wyjątku PHP, a nie według łańcuchowego kodu błędu, a wyjątki świadome kontekstu niosą strukturalne pola diagnostyczne. Baza wiedzy rozwiązywania problemów mapuje typowe awarie podpisu, PDF/A, PDF/UA, czcionek, tagowania i szyfrowania na ich przyczynę i rozwiązanie.