Branding — szczegółowa referencja

W skrócie

Ta strona to szczegółowa referencja modułu NextPDF\Enterprise\Branding. Moduł oznacza wynik ewaluacyjny i pozostawia wynik płatny nietknięty. BrandingMode rozwiązany na podstawie licencji wybiera strategię; BrandingApplicator nakłada rozwiązaną strategię na wyrenderowane bajty PDF. Przy płatnej licencji transformacja jest identycznością: wynik jest bajt w bajt niezmieniony, bez żadnej wymaganej zmiany kodu. Aby poznać przepływ ewaluacyjny, przeczytaj najpierw stronę możliwości Branding.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Podsystem niesie dedykowany kod możliwości enterprise.branding, ponieważ zarządza zachowaniem ewaluacyjnym we wszystkich edycjach. Tryb brandingu jest rozwiązywany z podpisanej koperty licencyjnej w czasie wykonywania; nie wybiera go żadna flaga aplikacji. Płatna licencja rozwiązuje tryb na None i nigdy nie wytwarza wyniku z brandingiem. Nie ma żadnej kompilacji produkcyjnej, którą trzeba by przełączać.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
BrandingMode	—	None ('none'): brak modyfikacji	—	—	Enum oparty na łańcuchu; EvaluationWatermark ('evaluation') aktywuje branding ewaluacyjny.
BrandingStrategy	—	Kontrakt konsumowany przez punkty integracji	—	—	Interfejs; wywołujący nigdy nie rozgałęziają się bezpośrednio na BrandingMode.
BrandingStrategy::isActive	—	false dla strategii null, true dla strategii ewaluacyjnej	bool	—	false oznacza, że każda inna metoda zwraca wartości tożsamościowe.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (punkty)	Pusty łańcuch, gdy nieaktywna; operatory ukośnego znaku wodnego, gdy aktywna	string	—	Strumień zakłada zasób czcionki /helvetica na stronie.
BrandingStrategy::decorateProducer	string $producer	Tożsamość, gdy nieaktywna; dopisuje przyrostek ewaluacyjny, gdy aktywna	string	—	Domyślny przyrostek: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Tożsamość, gdy nieaktywna; poprzedza prefiksem ewaluacyjnym, gdy aktywna	string	—	Pusty temat daje przycięty znacznik.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	Odwzorowuje None na NullBrandingStrategy, EvaluationWatermark na EvaluationBrandingStrategy	BrandingStrategy	—	Statyczna; konfiguracja null używa wartości domyślnych.
EvaluationBrandingConfig::__construct	Sześć opcjonalnych parametrów nazwanych (tekst, przyrostek, prefiks, rozmiar, szarość, kąt)	Domyślnie: 48 pt, szarość 0.85, 45 stopni	Instancja	InvalidArgumentException przy pustym tekście, niedodatnim rozmiarze czcionki lub szarości poza zakresem 0.0–1.0	final readonly; niezmienna.
EvaluationBrandingStrategy	Opcjonalny EvaluationBrandingConfig	Nakłada znak wodny i dekorowanie metadanych	—	—	final readonly; implementuje BrandingStrategy.
NullBrandingStrategy	—	Tożsamość w każdej metodzie	—	—	Wybierana przy płatnej licencji.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Strategia nieaktywna: wejście zwracane bajt w bajt; aktywna: dopisana jedna aktualizacja przyrostowa	string	BrandingApplicationException, gdy aktywnego brandingu nie da się bezpiecznie nałożyć	Czysta, deterministyczna transformacja bajtów.
BrandingApplicationException	—	Terminalny sygnał awarii fail-closed	—	—	Niesie SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE); fabryka unsupportedStructure().

Sygnatury punktów wejścia

enum BrandingMode: string
{
    case None = 'none';
    case EvaluationWatermark = 'evaluation';
}

public static function create(
    BrandingMode $mode,
    ?EvaluationBrandingConfig $config = null,
): BrandingStrategy

public function __construct(
    public string $watermarkText = 'EVALUATION COPY — Not for Production Use',
    public string $producerSuffix = ' [EVALUATION]',
    public string $subjectPrefix = '[EVALUATION] ',
    public float $watermarkFontSize = 48.0,
    public float $watermarkGray = 0.85,
    public float $watermarkAngle = 45.0,
)

public function apply(string $pdfBytes, BrandingStrategy $strategy): string

Kontrakt zachowania

Rozwiązanie trybu i strategii. Stan licencji — a nie kod aplikacji — wybiera BrandingMode. BrandingStrategyFactory::create odwzorowuje None na NullBrandingStrategy, a EvaluationWatermark na EvaluationBrandingStrategy. Punkty integracji konsumują interfejs BrandingStrategy i nigdy nie sprawdzają trybu bezpośrednio, dzięki czemu logika brandingu pozostaje scentralizowana. Przy płatnej licencji wybierana jest strategia null, a wynik jest identyczny z wynikiem wytworzonym całkowicie bez podsystemu brandingu.

Generowanie znaku wodnego. buildPageWatermark emituje operatory strumienia treści PDF dla jednej strony: izolowany stan graficzny (q/Q), czcionkę Helvetica ze standardowej czternastki poprzez nazwę zasobu /helvetica, tryb renderowania tekstu z wypełnieniem oraz macierz obrotu, która umieszcza tekst ukośnie przez środek strony. Styl domyślny to tekst 48 pt na poziomie szarości 0.85, obrócony o 45 stopni. Wyśrodkowanie przybliża szerokość tekstu na podstawie liczby glifów — klastry grafemów, gdy załadowane jest intl, punkty kodowe Unicode poprzez mbstring w przeciwnym razie, długość w bajtach jako ostateczny wariant awaryjny. Z założenia nie są konsultowane szerokości przesunięcia poszczególnych glifów. Tekst znaku wodnego jest escapowany jako łańcuch literalny PDF zgodnie z ISO 32000-2:2020 §7.3.4.2 (odwrotny ukośnik i nawiasy).

Dekorowanie metadanych. decorateProducer dopisuje przyrostek producenta do wartości /Producer. decorateSubject poprzedza wartość /Subject prefiksem tematu; pusty temat daje przycięty znacznik, więc dokument bez metadanych tematu również zostaje oznaczony.

Nakładanie na bajty. BrandingApplicator::apply jest terminalnym konsumentem kontroli brandingu. Przy strategii nieaktywnej zwraca wejście bajt w bajt. Przy strategii aktywnej dopisuje pojedynczą aktualizację przyrostową w kształcie zdefiniowanym przez ISO 32000-2:2020 §7.5.6: oryginalne bajty pozostają nienaruszone, a dopisane ciało zawiera udekorowany obiekt Info (ponownie wykorzystując istniejący numer obiektu), jeden strumień treści znaku wodnego oraz jeden zaktualizowany obiekt strony na stronę, a także nowy strumień odsyłaczy (/Type /XRef, /W [1 4 2]), którego /Prev wskazuje z powrotem na poprzedni startxref. Transformacja jest czysta i deterministyczna dla danego wejścia i danej konfiguracji.

Kontrakt fail-closed. Gdy strategia jest aktywna, wejście musi nadawać się do brandingu: nagłówek %PDF-, brak wpisu /Encrypt, brak strumieni obiektów (/ObjStm), zakończenie strumieniem odsyłaczy oraz zasób czcionki /helvetica rozwiązywalny z każdej strony. Każde naruszenie zgłasza BrandingApplicationException zamiast zwracać bajty bez brandingu. Wywołujący muszą traktować wyjątek jako terminalny i nie mogą zatwierdzać oryginalnych, nieoznaczonych bajtów.

Przypadki brzegowe i tryby awarii

• Wynik z brandingiem oznacza, że stan licencji jest w stylu ewaluacyjnym. Odzwierciedla to stan licencji, a nie defekt.
• Znak wodny jest z założenia wyśrodkowany i ukośny. Nie jest dostrajalny do użytku produkcyjnego; płatna licencja usuwa go całkowicie.
• EvaluationBrandingConfig odrzuca pusty tekst znaku wodnego, niedodatni rozmiar czcionki oraz poziom szarości poza zakresem 0.0–1.0 z InvalidArgumentException.
• Aktywna strategia, która nie wytwarza żadnej zmiany Producer, Subject ani znaku wodnego, jest odrzucana z BrandingApplicationException zamiast emitować bajty wyglądające na płatne.
• Strona bez użytecznego /MediaBox (nieobecnego lub dziedziczonego) otrzymuje znak wodny w domyślnym formacie ISO 216 A4 wynoszącym 595.276 × 841.890 punktów.
• /Contents jest obsługiwane zarówno w postaci pojedynczego odwołania, jak i tablicy; odwołanie znaku wodnego jest dopisywane na końcu, aby rysowało się na wierzchu. Strona bez /Contents otrzymuje jedno.
• Wartości łańcuchowe Info zachowują swoją oryginalną reprezentację: łańcuchy szesnastkowe (UTF-16BE) pozostają szesnastkowe, łańcuchy literalne pozostają literalne. Nieobecny klucz jest dopisywany, kodowany szesnastkowo, gdy wartość zawiera znaki spoza ASCII.
• Dokumenty zaszyfrowane są odrzucane: przepisanie obiektów łańcuchowych pod /Encrypt wymagałoby klucza szyfrowania dokumentu.
• Awarie niosą stabilny kod SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE), aby konsumujące potoki mogły kierować do kolejki niedostarczonych i audytować wynik nienadający się do brandingu.
• Moduł nie wykonuje żadnych operacji kryptograficznych. Weryfikacja podpisu koperty licencyjnej należy do podsystemu licencjonowania; zobacz szczegółową referencję licencjonowania.

Zgodność

Twierdzenie	Standard	Klauzula
Aktualizacje przyrostowe dopisują zmiany na końcu pliku i pozostawiają oryginalną treść nienaruszoną.	ISO 32000-2	§7.5.6
Sekcja odsyłaczy aktualizacji obejmuje tylko zmienione obiekty, a dodany trailer niesie wpis Prev lokalizujący poprzednią sekcję odsyłaczy.	ISO 32000-2	§7.5.6
Łańcuchy literalne są zapisywane w nawiasach; niezrównoważone nawiasy oraz odwrotny ukośnik wymagają traktowania escapem.	ISO 32000-2	§7.3.4.2

Wszystkie klauzule są parafrazowane; NextPDF nie reprodukuje tekstu normatywnego. NextPDF nie składa żadnego oświadczenia o certyfikacji. Aplikator zapisuje aktualizacje przyrostowe w cytowanym kształcie ISO 32000-2 jako deklarację możliwości; nie jest certyfikowanym ani niezależnie zwalidowanym zapisującym. Ta strona opisuje wyłącznie zachowanie w czasie wykonywania. Nie daje żadnej gwarancji, żadnego oświadczenia o uprawnieniach ani skutku prawnym i nie stanowi porady prawnej; warunki ewaluacji lub subskrypcji są definiowane wyłącznie umową licencyjną.

Uwagi deweloperskie

• BrandingMode, BrandingStrategy, obie strategie oraz konfiguracja niosą @since 3.0.0; BrandingApplicator i BrandingApplicationException niosą @since 3.1.0.
• Podsystem nie wykonuje żadnych wywołań sieciowych. Aplikator odczytuje tylko pola strukturalne, które przepisuje: łańcuchy słownika Info, słowniki stron oraz zakończenie odsyłaczy.
• Koperta licencyjna jest podpisanym artefaktem, którego podpis wystawcy weryfikuje środowisko uruchomieniowe. Udostępnianie, odnawianie oraz bezpieczne przechowywanie licencji należą do odpowiedzialności operatora.
• Wszystkie typy konkretne są final; strategie oraz konfiguracja są też readonly. Utwórz nową instancję konfiguracji, aby zmienić styl znaku wodnego.
• BrandingStrategy::isActive() zwracające false gwarantuje wartości tożsamościowe z każdej innej metody; wywołujący mogą na tej podstawie stosować skrót dla wydajności.
• Strumień znaku wodnego odwołuje się do nazwy zasobu /helvetica. Core rejestruje ten zasób dla własnego brandingu; integracja wyłączająca branding Core musi zapewnić, że zasób istnieje.
• Aplikator nie oblicza żadnego skrótu; wywołujący ponownie oblicza skrót bajtów z brandingiem przed ich zatwierdzeniem.
• Szczegóły wewnętrznego mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i wykraczają poza zakres tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń wykraczają poza zakres.

Zobacz też

• Branding — strona możliwości podsystemu brandingu ewaluacyjnego.
• Wersja próbna i branding ewaluacyjny — pełna historia ewaluacji.
• Licensing — szczegółowa referencja
• Przegląd Enterprise