Branding — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Enterprise\Branding modülü için derinlemesine referanstır. Modül, değerlendirme çıktısını işaretler ve ücretli çıktıya dokunmaz. Lisanstan çözümlenen bir BrandingMode bir strateji seçer; BrandingApplicator, çözümlenen stratejiyi işlenmiş PDF baytlarına uygular. Ücretli bir lisans altında dönüşüm özdeşliktir: çıktı bayt-bayt değişmemiştir ve hiçbir kod değişikliği gerekmez. Değerlendirme iş akışı için önce Markalama yetenek sayfasını okuyun.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile sunulur ve bir Enterprise katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

Alt sistem, tüm sürümler genelinde değerlendirme davranışını yönettiği için özel enterprise.branding yetenek kodunu taşır. Markalama kipi, çalışma zamanında imzalı lisans zarfından çözümlenir; onu hiçbir uygulama bayrağı seçmez. Ücretli bir lisans, kipi None olarak çözümler ve asla markalanmış çıktı üretmez. Geçiş yapılacak hiçbir üretim derlemesi yoktur.

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
BrandingMode	—	None ('none'): değişiklik yok	—	—	String tabanlı enum; EvaluationWatermark ('evaluation') değerlendirme markalamasını etkinleştirir.
BrandingStrategy	—	Entegrasyon noktalarınca tüketilen sözleşme	—	—	Arayüz; çağıranlar asla doğrudan BrandingMode üzerinde dallanmaz.
BrandingStrategy::isActive	—	Boş strateji için false, değerlendirme stratejisi için true	bool	—	false, diğer her yöntemin özdeşlik değerleri döndürdüğü anlamına gelir.
BrandingStrategy::buildPageWatermark	float $pageWidth, float $pageHeight (nokta)	Etkin değilken boş dize; etkinken çapraz filigran işleçleri	string	—	Akış, sayfada bir /helvetica yazı tipi kaynağı varsayar.
BrandingStrategy::decorateProducer	string $producer	Etkin değilken özdeşlik; etkinken değerlendirme sonekini ekler	string	—	Varsayılan sonek: [EVALUATION].
BrandingStrategy::decorateSubject	string $subject	Etkin değilken özdeşlik; etkinken değerlendirme önekini başa ekler	string	—	Boş konu, kırpılmış işareti verir.
BrandingStrategyFactory::create	BrandingMode $mode, ?EvaluationBrandingConfig $config = null	None’u NullBrandingStrategy’ye, EvaluationWatermark’ı EvaluationBrandingStrategy’ye eşler	BrandingStrategy	—	Statik; null yapılandırma varsayılanları kullanır.
EvaluationBrandingConfig::__construct	Altı isteğe bağlı adlandırılmış parametre (metin, sonek, önek, boyut, gri, açı)	Varsayılanlar: 48 pt, gri 0.85, 45 derece	Örnek	Boş metinde, pozitif olmayan yazı tipi boyutunda veya 0.0–1.0 dışındaki gride InvalidArgumentException	final readonly; değişmez.
EvaluationBrandingStrategy	İsteğe bağlı EvaluationBrandingConfig	Filigran ve meta veri süslemesi uygular	—	—	final readonly; BrandingStrategy’yi uygular.
NullBrandingStrategy	—	Her yöntemde özdeşlik	—	—	Ücretli bir lisans altında seçilir.
BrandingApplicator::apply	string $pdfBytes, BrandingStrategy $strategy	Etkin olmayan strateji: girdi bayt-bayt döndürülür; etkin: bir artımlı güncelleme eklenir	string	Etkin markalama güvenli biçimde uygulanamadığında BrandingApplicationException	Saf, belirlenimci bayt dönüşümü.
BrandingApplicationException	—	Sonlandırıcı, fail-closed başarısızlık sinyali	—	—	SPEC_CODE (SPEC-BRANDING-UNAPPLICABLE) taşır; fabrika unsupportedStructure().

Giriş noktası imzaları

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

Davranış sözleşmesi

Kip ve strateji çözümleme. BrandingMode’u uygulama kodu değil, lisans durumu seçer. BrandingStrategyFactory::create, None’u NullBrandingStrategy’ye ve EvaluationWatermark’ı EvaluationBrandingStrategy’ye eşler. Entegrasyon noktaları BrandingStrategy arayüzünü tüketir ve kipi asla doğrudan incelemez; böylece markalama mantığı merkezî kalır. Ücretli bir lisans altında boş strateji seçilir ve çıktı, hiç markalama alt sistemi olmadan üretilen çıktıyla özdeştir.

Filigran oluşturma. buildPageWatermark, tek bir sayfa için PDF içerik-akışı işleçleri yayar: yalıtılmış bir grafik durumu (q/Q), /helvetica kaynak adı üzerinden standart-14 Helvetica yazı tipi, dolgu metin işleme kipi ve metni sayfa merkezi boyunca çapraz yerleştiren bir döndürme matrisi. Varsayılan biçem, gri düzeyi 0.85’te 48 pt metindir ve 45 derece döndürülmüştür. Ortalama, metin genişliğini glif sayısıyla yaklaşıklar — intl yüklüyken grafem kümeleri, aksi hâlde mbstring üzerinden Unicode kod noktaları, son geri dönüş olarak bayt uzunluğu. Tasarım gereği glif başına ilerleme genişliklerine başvurulmaz. Filigran metni, ISO 32000-2:2020 §7.3.4.2 uyarınca bir PDF sabit dizesi olarak kaçışlanır (ters eğik çizgi ve parantezler).

Meta veri süslemesi. decorateProducer, üretici sonekini /Producer değerine ekler. decorateSubject, konu önekini /Subject değerinin başına ekler; boş bir konu, kırpılmış işareti verir; böylece konu meta verisi olmayan bir belge yine de işaretlenir.

Bayt uygulaması. BrandingApplicator::apply, markalama denetiminin sonlandırıcı tüketicisidir. Etkin olmayan bir strateji ile girdiyi bayt-bayt döndürür. Etkin bir strateji ile ISO 32000-2:2020 §7.5.6 tarafından tanımlanan biçimde tek bir artımlı güncelleme ekler: özgün baytlar bozulmadan kalır ve eklenen gövde, süslenmiş bir Info nesnesi (var olan nesne numarasını yeniden kullanarak), sayfa başına bir filigran içerik akışı artı bir güncellenmiş sayfa nesnesi ve /Prev’i önceki startxref’e geri işaret eden yeni bir çapraz başvuru akışı (/Type /XRef, /W [1 4 2]) tutar. Dönüşüm, belirli bir girdi ve yapılandırma için saf ve belirlenimcidir.

Fail-closed sözleşmesi. Strateji etkinken girdi markalanabilir olmalıdır: bir %PDF- üst bilgisi, /Encrypt girdisi yok, nesne akışları (/ObjStm) yok, bir çapraz başvuru akışı kuyruğu ve her sayfadan çözümlenebilir bir /helvetica yazı tipi kaynağı. Herhangi bir ihlal, markalanmamış baytları döndürmek yerine BrandingApplicationException fırlatır. Çağıranlar istisnayı sonlandırıcı olarak ele almalı ve özgün, işaretlenmemiş baytları işlememelidir.

Uç durumlar ve başarısızlık kipleri

• Markalanmış çıktı, lisans durumunun değerlendirme biçeminde olduğu anlamına gelir. Bu, bir kusuru değil, lisans durumunu yansıtır.
• Filigran tasarım gereği ortalanmış ve çaprazdır. Üretim kullanımı için ayarlanabilir değildir; ücretli bir lisans onu tamamen kaldırır.
• EvaluationBrandingConfig, boş filigran metnini, pozitif olmayan bir yazı tipi boyutunu ve 0.0–1.0 dışındaki bir gri düzeyini InvalidArgumentException ile reddeder.
• Hiçbir Producer, Subject veya filigran değişikliği üretmeyen etkin bir strateji, ücretli görünen baytlar yaymaktansa BrandingApplicationException ile reddedilir.
• Kullanılabilir bir /MediaBox olmayan (eksik veya devralınmış) bir sayfa, ISO 216 A4 varsayılanı olan 595.276 × 841.890 noktada filigranlanır.
• /Contents’in tek başvuru ve dizi biçimlerinin ikisi de desteklenir; filigran başvurusu en üste çizilsin diye en sona eklenir. /Contents olmayan bir sayfa bir tane alır.
• Info dize değerleri özgün gösterimlerinde gidiş-dönüş yapar: onaltılık dizeler (UTF-16BE) onaltılık kalır, sabit dizeler sabit kalır. Eksik bir anahtar eklenir; değer ASCII olmayan karakterler içerdiğinde onaltılık kodlanır.
• Şifreli belgeler reddedilir: /Encrypt altında dize nesnelerini yeniden yazmak, belge şifreleme anahtarını gerektirir.
• Başarısızlıklar, kararlı SPEC-BRANDING-UNAPPLICABLE (BrandingApplicationException::SPEC_CODE) kodunu taşır; böylece tüketen ardışık düzenler markalanamayan çıktıyı ölü-mektuba alabilir ve denetleyebilir.
• Modül hiçbir kriptografik işlem yapmaz. Lisans-zarfı imza doğrulaması lisanslama alt sistemine aittir; bkz. Lisanslama derinlemesine referansı.

Uygunluk

İddia	Standart	Madde
Artımlı güncellemeler değişiklikleri dosyanın sonuna ekler ve özgün içeriği bozulmadan bırakır.	ISO 32000-2	§7.5.6
Güncellemenin çapraz başvuru bölümü yalnızca değişen nesneleri kapsar ve eklenen trailer, önceki çapraz başvuru bölümünü konumlandıran bir Prev girdisi taşır.	ISO 32000-2	§7.5.6
Sabit dizeler parantez içinde yazılır; dengesiz parantezler ve ters bölü işareti kaçış işlemi gerektirir.	ISO 32000-2	§7.3.4.2

Tüm maddeler başka sözcüklerle ifade edilmiştir; NextPDF normatif metni yeniden üretmez. NextPDF hiçbir sertifikasyon iddiasında bulunmaz. Uygulayıcı, artımlı güncellemeleri bir yetenek beyanı olarak, atıf yapılan ISO 32000-2 biçiminde yazar; sertifikalı veya bağımsız olarak doğrulanmış bir yazıcı değildir. Bu sayfa yalnızca çalışma zamanı davranışını açıklar. Hiçbir garanti, uygunluk veya hukuki etki hakkında hiçbir beyanda bulunmaz ve hukuki tavsiye oluşturmaz; bir değerlendirmenin veya aboneliğin koşulları yalnızca lisans sözleşmesince tanımlanır.

Geliştirme notları

• BrandingMode, BrandingStrategy, her iki strateji ve yapılandırma @since 3.0.0 taşır; BrandingApplicator ve BrandingApplicationException @since 3.1.0 taşır.
• Alt sistem hiçbir ağ çağrısı yapmaz. Uygulayıcı yalnızca yeniden yazdığı yapısal alanları okur: Info sözlüğü dizeleri, sayfa sözlükleri ve çapraz başvuru kuyruğu.
• Lisans zarfı, düzenleyen imzasını çalışma zamanının doğruladığı imzalı bir yapıttır. Lisans sağlama, yenileme ve güvenli depolama operatörün sorumluluğundadır.
• Tüm somut türler final’dir; stratejiler ve yapılandırma ayrıca readonly’dir. Filigran biçemini değiştirmek için yeni bir yapılandırma örneği oluşturun.
• BrandingStrategy::isActive()’in false döndürmesi, diğer her yöntemden özdeşlik değerlerini garanti eder; çağıranlar başarım için bunun üzerinde kısa devre yapabilir.
• Filigran akışı /helvetica kaynak adına başvurur. Core, bu kaynağı kendi markalaması için kaydeder; Core markalamasını devre dışı bırakan bir entegrasyon, kaynağın var olmasını sağlamalıdır.
• Uygulayıcı hiçbir özet hesaplamaz; çağıran, markalanmış baytları işlemeden önce yeniden özetler.
• Dahilî mekanizma ayrıntısı, kaynak deposunun dahilî belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bakınız

• Branding — değerlendirme-markalama alt sistemi için yetenek sayfası.
• Deneme ve değerlendirme markalaması — uçtan uca değerlendirme öyküsü.
• Lisanslama — derinlemesine referans
• Enterprise genel bakışı