Template

Bir bakışta

NextPDF\Pro\Template, bir JSON şablon tanımını türlenmiş bir değer nesnesine ayrıştırır ve ilişkisel bir veri dizisini tür duyarlı biçimlendirmeyle yer tutucularına bağlar. Yapılandırılmış bir bağlama sonucu üretir; kendisi bir PDF işlemez.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) içinde sağlanır ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Katman lisansının ötesinde hiçbir ek çalışma zamanı yetenek bayrağı bu modülü kapılamaz. Sürümleri karşılaştırın ve lisans edinin.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

Bir şablon, bir sayfa düzenini ve konumlandırılmış yer tutucuların bir listesini açıklayan bir JSON belgesidir. TemplateParser, JSON’u doğrular ve değişmez bir TemplateDefinition üretir. Doğrulama sıkıdır: sayfa boyutunu bir izin listesine (A3–A6, B4, B5, Letter, Legal, Tabloid) göre, yönelimi (P veya L) ve her yer tutucunun adını, türünü ve sayısal koordinatlarını denetler ve yinelenen yer tutucu adlarını reddeder.

TemplateDataBinder, bir veri dizisini (yer tutucu adlarıyla büyük/küçük harf duyarsız eşleştirilerek) bağlar ve her değeri PlaceholderType ile biçimlendirir:

• Text / Image / Barcode — değer bir dize olarak olduğu gibi geçirilir.
• Date — yer tutucunun biçimiyle (varsayılan Y-m-d) biçimlendirilir; dizeleri, Unix zaman damgalarını veya DateTimeInterface değerlerini kabul eder.
• Number — biçimden alınan ondalıklarla number_format (varsayılan 2).
• Currency — biçim dizesi bir önek olarak kullanılarak biçimlendirilen sayı (varsayılan $).
• Conditional — doğruluğa göre "true" veya "false".

Sonuç, bağlanan değerleri, eksik zorunlu alanların listesini ve varsa biçimlendirme uyarılarını taşıyan bir BindingResult’tır. Bağlanan değerleri işlenmiş bir PDF’ye dönüştürmek, Core belge ve yazıcı API’lerini ve isteğe bağlı backgroundPdf başvurusunu kullanarak çağıranın sorumluluğudur.

Neden bu şekilde çalışır

Ayrıştırıcı, tek yetkili kapıdır. Güvenilmeyen JSON’u değişmez, tamamen türlenmiş bir TemplateDefinition haline getirir ve bağlama ardından bu değerin saf bir işlevi olarak çalışır. Daha sonra bir biçimlendirme alıcısına ulaşan her alan, ayrıştırma zamanında izin listesine alınır ve uzunluğu sınırlanır. Sayfa boyutu, yönelim, sayı hassasiyeti ve denetim karakterleri, işleme ortasında değil, burada başarısız olur. Dize tarihleri sabit bir kanonik biçimler kümesine göre eşleştirilir; böylece now veya +1 year gibi bir değer, çıktının duvar saatine bağlı olmasına yol açamaz. Modül, kasıtlı olarak bir BindingResult’ta durur ve işlemeyi, yol çözümlemesini ve arka plan birleştirmesini çağırana bırakır; bu da güven sınırını açık tutar.

Tasarım arka planı: Faturalar ve e-faturalama.

Davranış sözleşmesi

• Giriş. Bir JSON dizesi (TemplateParser) ve bir veri dizisi (TemplateDataBinder).
• Çıkış. Ayrıştırmadan TemplateDefinition; bağlamadan BindingResult.
• Doğrulama. validate(), insan tarafından okunabilir hataların bir listesini döndürür ve asla fırlatmaz; parse(), doğrulama başarısız olduğunda InvalidArgumentException fırlatır.
• Eksik veri. Verisi olmayan ve boş bir varsayılana sahip bir yer tutucu, missingFields içinde bildirilir; boş olmayan bir varsayılana sahip olan varsayılanı kullanır.
• Belirlenimcilik. Ayrıştırma ve bağlama, girdilerinin saf işlevleridir.

Genel API yüzeyi

Tür	Çeşit	Temel üyeler
NextPDF\Pro\Template\TemplateParser	final class	parse(string $json): TemplateDefinition, validate(string $json): list<string>
NextPDF\Pro\Template\TemplateDataBinder	final class	bind(TemplateDefinition $template, array $data): BindingResult
NextPDF\Pro\Template\TemplateDefinition	final readonly class	string $name, string $pageSize, string $orientation, array $placeholders, string $backgroundPdf, getPlaceholder(string $name): ?TemplatePlaceholder, requiredFields(): list<string>
NextPDF\Pro\Template\TemplatePlaceholder	final readonly class	ad, PlaceholderType $type, koordinatlar, varsayılan, biçim
NextPDF\Pro\Template\BindingResult	final readonly class	array $bindings, array $missingFields, array $warnings
NextPDF\Pro\Template\PlaceholderType	enum	Text, Image, Barcode, Date, Number, Currency, Conditional; requiresFormatting(): bool

Kod örneği — hızlı başlangıç

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

$json = '{"name":"Invoice","pageSize":"A4","orientation":"P","placeholders":'
 . '[{"name":"total","type":"currency","x":400,"y":700,"width":120,'
 . '"height":18,"format":"$"}]}';

$template = (new TemplateParser())->parse($json);
$result = (new TemplateDataBinder())->bind($template, ['total' => 1299.5]);

foreach ($result->bindings as $bound) {
 echo $bound->placeholder->name, ' => ', $bound->formattedValue, "\n";
}

Kod örneği — üretim

<?php

declare(strict_types=1);

use NextPDF\Pro\Template\TemplateDataBinder;
use NextPDF\Pro\Template\TemplateParser;

function bindOrReject(string $json, array $data): array
{
 $parser = new TemplateParser();

 $errors = $parser->validate($json);
 if ($errors !== []) {
 throw new InvalidArgumentException(implode('; ', $errors));
 }

 $template = $parser->parse($json);
 $result = (new TemplateDataBinder())->bind($template, $data);

 if ($result->missingFields !== []) {
 throw new RuntimeException(
 'missing required fields: ' . implode(', ', $result->missingFields),
 );
 }

 return $result->bindings; // hand to the renderer
}

Uç durumlar ve tuzaklar

• Ayrıştırılamayan bir tarih dizesi bir uyarı üretir ve fırlatma yerine özgün dize korunur.
• Para birimi biçim dizesi, bir yerel ayar tanımlayıcısı değil, sabit bir önek olarak kullanılır (örneğin "$" veya "EUR ").
• backgroundPdf, tanımda taşınan bir yol başvurusudur; bu modül onu açmaz, doğrulamaz veya birleştirmez — bu, oluşturucunun işidir.
• Yer tutucu adları büyük/küçük harf duyarsız eşleştirilir; JSON’daki yinelenen adlar bir doğrulama hatasıdır.

Performans

Ayrıştırma, bir JSON kod çözme artı yapısal doğrulamadır; bağlama, yer tutucu sayısında doğrusaldır. performance_budget bölümüne bakın.

Güvenlik notları

JSON, bir TemplateDefinition oluşturulmadan önce JSON_THROW_ON_ERROR ile çözülür ve sabit izin listelerine göre doğrulanır. Modül, hiçbir dosya veya ağ giriş/çıkışı gerçekleştirmez; backgroundPdf yolu burada başvurusu çözülmez; bu nedenle yol işleme ve erişim denetimi oluşturucuya aittir.

Uygunluk

Bu modülün doğrudan bir PDF belirtim yüzeyi yoktur: bir JSON şablonu ayrıştırır ve değerleri biçimlendirir. Sayfa boyutu ve yönelim sözcük dağarcıkları, normatif PDF yapıları değil, NextPDF kurallarıdır.

Core yedeği / alternatifi

Bir Core şablon tanım katmanı yoktur. Tamamen buyurgan belge oluşturma için açık kaynaklı Core belge ve yazıcı API’lerini doğrudan kullanın. /modules/core/document/ bölümüne bakın.

Enterprise sınır notu

Bu modül şablonları tanımlar ve bağlar. Posta birleştirme düzenlemesi, toplu iş zamanlaması veya işleme gerçekleştirmez; bu konular kapsam dışıdır ve başka yerde ele alınır.

Yayımlama sınırı

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

Ayrıca bkz.

• Şablon başvurusu
• Toc
• Merge
• Core belge modeli