Branding

W skrócie

Podsystem brandingu nakłada widoczny branding ewaluacyjny na generowane pliki PDF podczas ewaluacji, a pod płatną licencją nie nakłada niczego. Jest dostarczany w pakiecie nextpdf/enterprise, reguluje zachowanie ewaluacyjne we wszystkich edycjach i jest sterowany w całości przez licencję — a nie przez kod aplikacji. Pełną historię ewaluacji od początku do końca opisuje Wersja próbna i branding ewaluacyjny; ta strona dokumentuje sam podsystem brandingu.

Dostępność i licencjonowanie

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

W przeciwieństwie do większości powierzchni Enterprise ma dedykowany kod możliwości, enterprise.branding, ponieważ reguluje zachowanie ewaluacyjne we wszystkich edycjach — w tym we wdrożeniach wyłącznie z Core i wyłącznie z Pro. Tryb brandingu jest rozwiązywany z podpisanej koperty licencyjnej w czasie wykonania; żadna flaga aplikacji go nie wybiera, a płatna licencja w dowolnej edycji rozwiązuje się na BrandingMode::None.

Instalacja

composer require nextpdf/enterprise:^3

Przegląd koncepcyjny

Środowisko uruchomieniowe ma tryb brandingu o dwóch stanach, modelowany przez BrandingMode:

• None — brak brandingu ewaluacyjnego. Wynik płatny i normalny nigdy nie jest modyfikowany. To wartość domyślna.
• EvaluationWatermark — widoczny branding ewaluacyjny jest nakładany na generowane pliki PDF.

BrandingStrategyFactory mapuje tryb na strategię: NullBrandingStrategy dla None (nie wykonuje żadnej pracy i nie powoduje żadnej modyfikacji) oraz EvaluationBrandingStrategy dla EvaluationWatermark. Tryb wybiera stan licencji — a nie kod aplikacji. Płatna licencja nigdy nie wytwarza wyniku z brandingiem; nie ma kompilacji produkcyjnej do przełączenia ani flagi w kodzie do przestawienia.

Ta strona opisuje wyłącznie zachowanie w czasie wykonania. Nie udziela żadnej gwarancji ani nie formułuje żadnego twierdzenia o uprawnieniach czy skutkach prawnych; warunki mające zastosowanie do Twojej ewaluacji lub subskrypcji są zdefiniowane wyłącznie przez Twoją umowę licencyjną.

Powierzchnia API

Koncepcja	Zachowanie
BrandingMode	Dwa stany: None (domyślny, brak modyfikacji) lub EvaluationWatermark.
BrandingStrategyFactory	Rozwiązuje BrandingMode na strategię.
EvaluationBrandingStrategy	Nakłada znak wodny ewaluacji oraz dekorację metadanych.
NullBrandingStrategy	Strategia bez efektu (no-op) dla wyniku płatnego / normalnego.
EvaluationBrandingConfig	Niemutowalny tekst znaku wodnego, dekoracja metadanych, rozmiar czcionki, poziom szarości oraz kąt.
BrandingStrategy	Kontrakt konsumowany przez warstwę integracji: isActive(), buildPageWatermark(), decorateProducer(), decorateSubject().
BrandingApplicator	Nakłada rozwiązaną strategię na wyrenderowane bajty PDF; fail-closed — zgłasza BrandingApplicationException, gdy aktywnego brandingu nie można oznaczyć.

Podsystem udostępnia niewielką wywoływalną powierzchnię dla warstwy integracji, która nakłada strategię rozwiązaną przez licencję; kod aplikacji nigdy nie decyduje, czy nakładać branding. Poniższe przykłady pokazują dwa punkty styku: odczyt rozwiązanej strategii oraz oznaczanie wyrenderowanych bajtów za pomocą aplikatora typu fail-closed.

Przykład kodu — Szybki start

Rozwiąż strategię wybraną przez licencję i odczytaj jej zachowanie. Płatna licencja rozwiązuje się na BrandingMode::None, którego strategia jest nieaktywna i przepuszcza każdą wartość bez zmian.

resolve-strategy.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;

// The license resolves the mode; None is what a paid license produces.
$strategy = BrandingStrategyFactory::create(BrandingMode::None);

\var_dump($strategy->isActive());                 // bool(false)
echo $strategy->decorateProducer('NextPDF 3.1');  // NextPDF 3.1 (unchanged)

Przykład kodu — Produkcja

Oznacz już wyrenderowane bajty PDF strategią rozwiązaną przez licencję. BrandingApplicator::apply() zwraca dane wejściowe bez zmian dla płatnej licencji, a dla licencji ewaluacyjnej dołącza znak wodny i znaczniki metadanych, pozostawiając oryginalne bajty nienaruszone. Zgłasza BrandingApplicationException, gdy aktywnego brandingu nie można bezpiecznie nałożyć — potraktuj to jako sytuację terminalną i nigdy nie zatwierdzaj nieoznaczonych bajtów.

apply-evaluation-branding.php

<?php

declare(strict_types=1);

use NextPDF\Enterprise\Branding\BrandingApplicationException;
use NextPDF\Enterprise\Branding\BrandingApplicator;
use NextPDF\Enterprise\Branding\BrandingMode;
use NextPDF\Enterprise\Branding\BrandingStrategyFactory;
use NextPDF\Enterprise\Branding\EvaluationBrandingConfig;

/**
 * Apply the branding the license resolved to freshly rendered PDF bytes.
 *
 * @param string       $renderedPdf Bytes from the render engine.
 * @param BrandingMode $mode        Resolved from the signed license envelope.
 *
 * @throws BrandingApplicationException When active branding cannot be marked.
 */
function markEvaluationOutput(string $renderedPdf, BrandingMode $mode): string
{
    $strategy = BrandingStrategyFactory::create(
        $mode,
        new EvaluationBrandingConfig(
            watermarkText: 'EVALUATION COPY — Not for Production Use',
        ),
    );

    try {
        return (new BrandingApplicator())->apply($renderedPdf, $strategy);
    } catch (BrandingApplicationException $e) {
        // Fail-closed: never emit unbranded evaluation output. Dead-letter.
        throw $e;
    }
}

Co robi branding ewaluacyjny

Gdy aktywna licencja wybiera EvaluationWatermark, strategia ewaluacji:

• rysuje jasnoszary, diagonalny tekst znaku wodnego na każdej stronie, renderowany jako strumień treści strony w odizolowanym stanie graficznym, tak aby nie zmieniał otaczającej treści ani Twojego układu;
• dołącza ewaluacyjny przyrostek do metadanych producenta dokumentu;
• poprzedza ewaluacyjnym przedrostkiem metadane tematu dokumentu.

Znak wodny używa czcionki Base14 oraz macierzy obrotu, aby umieścić tekst diagonalnie przez środek strony. Obiekt konfiguracji jest niemutowalny i waliduje swoje dane wejściowe (na przykład tekst znaku wodnego nie może być pusty, a rozmiar czcionki musi być dodatni).

Jak płatna licencja usuwa branding

Pod płatną (nieewaluacyjną) licencją tryb brandingu to None i wybierana jest strategia null: brak znaku wodnego, brak przyrostka producenta, brak przedrostka tematu. Wynik jest identyczny z wynikiem wytworzonym całkowicie bez podsystemu brandingu. Usunięcie brandingu ewaluacyjnego nie wymaga żadnej zmiany w kodzie — zainstaluj płatną licencję, a następny wygenerowany dokument będzie bez brandingu.

Przypadki brzegowe i pułapki

• Branding pojawia się, gdy stan licencji jest typu ewaluacyjnego. Odzwierciedla to stan licencji, a nie defekt; sprawdź status licencji i odnów ją przez portal licencyjny.
• Znak wodny jest z założenia wyśrodkowany i diagonalny, aby wynik ewaluacyjny był jednoznaczny; nie jest przeznaczony do dostrajania na potrzeby produkcji. Płatna licencja usuwa go w całości.
• Metadane producenta i tematu niosą znaczniki ewaluacyjne podczas ewaluacji i są nieobecne pod płatną licencją.

Wydajność

Znak wodny to mały, stały strumień treści na każdą stronę, o pomijalnym wpływie na czas generowania lub rozmiar dokumentu. Pod płatną licencją podsystem nie wykonuje żadnej pracy. Budżet wydajności strony odzwierciedla renderowanie dokumentacji.

Uwagi dotyczące bezpieczeństwa

Branding ewaluacyjny to znacznik widoczności, a nie mechanizm kontroli bezpieczeństwa. Wskazuje wynik ewaluacyjny. Nie jest podpisem cyfrowym i nie wolno na nim polegać jak na podpisie. Aby uzyskać wynik z wykrywalną manipulacją, użyj możliwości podpisywania opisanych w macierzy funkcji. Licencja, która wybiera tryb brandingu, to podpisana koperta, której podpis wystawcy środowisko uruchomieniowe weryfikuje.

Rezydencja danych i środki ograniczające dla danych osobowych (PII)

Podsystem brandingu dodaje stały znak wodny oraz znaczniki metadanych; nie odczytuje ani nie przesyła treści dokumentu i nie wykonuje żadnych wywołań sieciowych.

Bezpieczna telemetria i czyszczenie logów

Podsystem nie loguje treści dokumentu. Przejścia stanu licencji, które zmieniają tryb brandingu, są ujawniane przez podsystem licencjonowania, a nie tutaj.

Zgodność ze standardami

Dla tej strony nie jest deklarowana żadna zgodność ze standardami. Opisuje ona wyłącznie zachowanie w czasie wykonania. Nie stwierdza ani nie sugeruje żadnej gwarancji, certyfikacji ani uprawnień. Warunki Twojej ewaluacji lub subskrypcji są zdefiniowane wyłącznie przez Twoją umowę licencyjną.

Zachowanie w trybie FIPS

Ten moduł nie wykonuje żadnych operacji kryptograficznych. Weryfikacja podpisu licencji jest obsługiwana przez podsystem licencjonowania.

Model zagrożeń

Sam podsystem brandingu nie przetwarza żadnych danych wejściowych z zewnątrz poza rozwiązanym trybem brandingu. Koperta licencyjna, która wybiera tryb, jest podpisana, a jej podpis wystawcy jest weryfikowany przez środowisko uruchomieniowe; sfałszowanie trybu wymagałoby podrobienia tego podpisu.

Kontrakt zachowania

• BrandingMode ma dwa stany: None (domyślny; brak modyfikacji wyniku) oraz EvaluationWatermark.
• Pod płatną (nieewaluacyjną) licencją tryb to None i wybierana jest strategia null: wynik jest identyczny z wynikiem wytworzonym całkowicie bez podsystemu brandingu.
• Pod licencją ewaluacyjną strategia rysuje diagonalny znak wodny w odizolowanym stanie graficznym i dołącza znaczniki ewaluacyjne do metadanych producenta i tematu.
• Obiekt konfiguracji jest niemutowalny i waliduje swoje dane wejściowe (tekst znaku wodnego niepusty, rozmiar czcionki dodatni).

Granica publikacji

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

Rozwiązanie awaryjne w Core

Podsystem brandingu jest dostarczany w pakiecie nextpdf/enterprise, ale reguluje zachowanie ewaluacyjne we wszystkich edycjach, w tym we wdrożeniach wyłącznie z Core i Pro, które używają licencji ewaluacyjnej. Nie ma podsystemu brandingu wyłącznie w Core, do którego można by się odwołać; płatna licencja w dowolnej edycji rozwiązuje się na BrandingMode::None.

Rozwiązanie awaryjne w Pro

Nie ma osobnego podsystemu brandingu w Pro. Ten sam podsystem brandingu nextpdf/enterprise reguluje zachowanie ewaluacyjne dla wdrożeń Pro; płatna licencja Pro rozwiązuje się na BrandingMode::None dokładnie tak, jak płatna licencja Enterprise.

Uwaga o granicy Enterprise

Szczegóły wewnętrznych mechanizmów pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica wdrożenia

Koperta licencyjna, która wybiera tryb brandingu, to podpisany artefakt, którego podpis wystawcy środowisko uruchomieniowe weryfikuje; udostępnianie licencji, jej odnawianie oraz bezpieczne przechowywanie są w gestii operatora. Podsystem nie wykonuje żadnych wywołań sieciowych i nie odczytuje treści dokumentu.

Granica zgodności prawnej

Ta strona opisuje wyłącznie zachowanie w czasie wykonania. Nie stwierdza ani nie sugeruje żadnej gwarancji, certyfikacji ani uprawnień i nie stanowi porady prawnej. Warunki Twojej ewaluacji lub subskrypcji — w tym jaki branding ma zastosowanie i na jak długo — są zdefiniowane wyłącznie przez Twoją umowę licencyjną. Skonsultuj się z tą umową lub skontaktuj się z działem sprzedaży.

Zobacz także

• Branding — głęboka referencja — publiczne API i kontrakt zachowania dla tego podsystemu.
• Wersja próbna i branding ewaluacyjny — historia ewaluacji od początku do końca.
• Aktywacja licencji
• Przegląd Enterprise
• Macierz funkcji: Core vs Pro vs Enterprise