Template — Derinlemesine başvuru

Bir bakışta

Bu derinlemesine başvuru; kabul edilen JSON şablon şemasını, her doğrulama kuralını ve veri bağlayıcısının tür başına tam biçimlendirme davranışını belgeler. Modül bir şablon tanımını ayrıştırır, ardından çağıran verisini türlenmiş yer tutuculara bağlar. Biçimlendirilmiş dizeler yayar; PDF nesneleri çizmez.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirme olmadan bir dağıtım, yeteneğin sınıflarını yüklemez. Hiçbir çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Sürümleri karşılaştırın ve lisans edinin.

Genel API yüzeyi

Modül, iki giriş noktası hizmeti ve dört değişmez değer nesnesi sunar. Aşağıdaki her simge herkese açık ve kararlıdır.

Simge	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
TemplateParser::parse	string $json	Doğrular, ardından tanımı oluşturur	TemplateDefinition	Herhangi bir doğrulama hatası varsa InvalidArgumentException	Önce validate’e devreder.
TemplateParser::validate	string $json	Tüm yapısal hataları tek geçişte toplar	list<string> (geçerliyken boş)	Asla fırlatmaz; bir JSON çözme hatası bir mesaj olarak döndürülür	Uzunluk ve kesinlik sınırları için yetkili kapı.
TemplateDataBinder::bind	TemplateDefinition $template, array<string,mixed> $data	Yer tutucuları büyük/küçük harf duyarsız eşleştirir ve türe göre biçimlendirir	BindingResult	Asla fırlatmaz; anormallikler uyarılara veya eksik alanlara dönüşür	Anahtar yoksa bir yer tutucu varsayılan değerini kullanır.
TemplateDefinition::__construct	string $name, string $pageSize, string $orientation, list<TemplatePlaceholder> $placeholders, string $backgroundPdf = ''	Ayrıştırılan tanımı saklar	TemplateDefinition	Bağımsız değişken tür uyuşmazlığında TypeError	Final readonly değer nesnesi.
TemplateDefinition::getPlaceholder	string $name	Ada göre büyük/küçük harf duyarsız arama	TemplatePlaceholder|null	Başarısızlık yok; yoksa null döndürür	—
TemplateDefinition::requiredFields	yok	Varsayılan değeri olmayan yer tutucuların adlarını toplar	list<string>	Başarısızlık yok	Boş olmayan bir varsayılan, yer tutucuyu isteğe bağlı işaretler.
TemplatePlaceholder::__construct	string $name, PlaceholderType $type, float $x, float $y, float $width, float $height, string $defaultValue = '', string $format = ''	Bir yer tutucu bölgesini saklar	TemplatePlaceholder	Bağımsız değişken tür uyuşmazlığında TypeError	Koordinatlar, sol üstten itibaren nokta cinsindendir.
TemplatePlaceholder::matches	string $key	Büyük/küçük harf duyarsız ad karşılaştırması	bool	Başarısızlık yok	—
BindingResult::__construct	list<BoundPlaceholder> $bindings, list<string> $missingFields, list<string> $warnings	Bağlama sonucunu saklar	BindingResult	Bağımsız değişken tür uyuşmazlığında TypeError	Final readonly değer nesnesi.
BindingResult::isComplete	yok	Her gerekli alanın bağlanıp bağlanmadığını bildirir	bool	Başarısızlık yok	missingFields boşken true.
BindingResult::count	yok	Başarıyla bağlanan yer tutucuları sayar	int	Başarısızlık yok	—
BoundPlaceholder::__construct	TemplatePlaceholder $placeholder, string $formattedValue, mixed $rawValue	Bir yer tutucuyu biçimlendirilmiş değeriyle eşleştirir	BoundPlaceholder	Bağımsız değişken tür uyuşmazlığında TypeError	Final readonly değer nesnesi.
PlaceholderType	enum durumları Text, Image, Barcode, Date, Number, Currency, Conditional	Dize destekli yer tutucu sınıflandırması	enum örneği	Bilinmeyen bir değerde from() tarafından ValueError	Bunun yerine tryFrom() null döndürür.
PlaceholderType::requiresFormatting	yok	Türün bir biçim dizesi tüketip tüketmediğini bildirir	bool	Başarısızlık yok	Date, Number, Currency için true.

final class TemplateParser
{
    public function parse(string $json): TemplateDefinition;
    public function validate(string $json): array;
}

final class TemplateDataBinder
{
    public function bind(TemplateDefinition $template, array $data): BindingResult;
}

Davranış sözleşmesi

Kabul edilen JSON biçimi:

{
  "name": "string (required, non-empty)",
  "pageSize": "A3|A4|A5|A6|B4|B5|Letter|Legal|Tabloid",
  "orientation": "P|L",
  "backgroundPdf": "optional path string",
  "placeholders": [
    { "name": "string", "type": "text|image|barcode|date|number|currency|conditional",
      "x": number, "y": number, "width": number, "height": number,
      "defaultValue": "optional", "format": "optional" }
  ]
}

validate tarafından mesaj olarak yüzeye çıkarılan ve parse tarafından tek bir istisnada toplanan doğrulama kuralları:

• Eksik veya boş name.
• İzin listesi dışında pageSize veya P ya da L olmayan orientation.
• Eksik placeholders veya dizi olmayan bir değer.
• Yer tutucu başına: eksik veya boş ad; geçersiz tür; eksik veya sayısal olmayan x, y, width, height; yinelenen ad (büyük/küçük harf duyarsız).
• defaultValue: dize olmayan, 4096 bayttan uzun veya bir ASCII denetim karakteri taşıyan.
• format: dize olmayan, 256 bayttan uzun veya bir ASCII denetim karakteri taşıyan.
• Negatif olmayan bir tam sayı olmayan veya 30’u aşan bir number yer tutucusu format’ı.

Bağlama anlam bilgisi (TemplateDataBinder::bind):

• Veri anahtarları, yer tutucu adlarıyla büyük/küçük harf duyarsız eşleştirme için küçük harfe dönüştürülür.
• Boş olmayan bir varsayılana sahip eksik bir anahtar varsayılanı bağlar; böyle bir varsayılanı olmayan eksik bir anahtar missingFields içinde bildirilir.
• Text, image ve barcode değerleri değiştirilmeden dizeye dönüştürülür.
• Tarih bağlama, bir DateTimeInterface, bir tam sayı Unix zaman damgası veya dört açık biçimden birindeki bir dizeyi kabul eder. Varsayılan çıktı biçimi Y-m-d’dir.
• Sayı bağlama number_format(value, decimals, '.', ',') kullanır. Ondalık sayısı format’tan gelir, varsayılanı 2’dir ve 0 ile 30 arasındaki aralıkla sınırlıdır.
• Para birimi bağlama, biçimlendirilmiş sayının önüne format ekler ve öneki varsayılan olarak $ yapar.
• Koşullu bağlama, bir boole dönüşümünden "true" veya "false" yayar.

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

• backgroundPdf bu modül tarafından asla açılmaz veya başvurusu çözülmez. Oluşturucuya verilen opak bir dizedir.
• Bir Number veya Currency yer tutucusuna bağlanan sayısal olmayan bir değer bir uyarı üretir; değer reddedilmez, dizeye dönüştürülür.
• Tarih dizeleri katı şekilde ayrıştırılır. Göreli ve doğal dildeki belirteçler (“now”, “+1 year”, “tomorrow”) kabul edilen hiçbir biçimle eşleşmez, bu nedenle uyarı verir ve ham değer değiştirilmeden geçer.
• Bir tam sayı tarih değeri, @ epoch biçimi aracılığıyla bir Unix zaman damgası olarak okunur.
• Bağlayıcıya ulaşan, 0 ile 30 dışındaki bir Number format kesinliği bir uyarıyla reddedilir; bağlayıcı, varsayılan kesinlik olan 2’ye geri döner.
• Bu modülde hiçbir kriptografik işlem gerçekleşmez, bu nedenle FIPS moduna özgü hiçbir davranış yoktur.

Uygunluk

Doğrudan bir PDF belirtim yüzeyi yoktur. Sayfa boyutu ve yönelim sözcük dağarcıkları NextPDF kurallarıdır ve bu modül PDF nesneleri değil, biçimlendirilmiş değerler yayar. Katı dize-tarih izin listesi; bir Y-m-d takvim tarihi ve iki yerel tarih-saat biçiminin yanı sıra, RFC 3339 §5.6’da tanımlanan ISO 8601’in İnternet tarih/saat profilini kabul eder. NextPDF, bu biçimleri okuma yeteneğini belgeler; RFC 3339 veya ISO 8601 karşısında hiçbir sertifikasyon iddia etmez.

Geliştirme notları

• TemplateParser ve TemplateDataBinder durumsuzdur. Tek bir örnek yeniden kullanılabilir ve bağlamalar arasında paylaşmak güvenlidir.
• Dört değer nesnesi final readonly’dir; bunları üretim girdisi için elle değil, ayrıştırıcı aracılığıyla oluşturun.
• validate her yapısal hatayı tek geçişte bildirirken, parse önce validate’i çağırır ve toplanan mesajda fırlatır. Form tarzı geri bildirim için validate’i, hızlı-başarısızlık alımı için parse’ı kullanın.
• Uzunluk ve kesinlik sınırları, yetkili kapı olarak ayrıştırıcıda uygulanır. TemplateDataBinder, number_format bellek yükseltmesine karşı bir alıcı tarafı koruması olarak sayı kesinliğini yeniden denetler.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, çalıştırma kılavuzu dosya adları ve talep önekleri kapsam dışıdır.

Ayrıca bkz.

• Template (yetenek kılavuzu)
• Toc
• Merge