Form — Derinlemesine başvuru

Bir bakışta

Bu sayfa, Pro Form modülü için derinlemesine başvurudur. AcroForm değer çıkarımını, XFDF okuma ve yazmayı, veri bağlamayı ve XFA veri çıkarımını kapsar. Modül, Core form okuyucunun ürettiği NextPDF\Form\FormField değerlerini tüketir ve bunların üzerine dizileştirme, ayrıştırma ve bağlama ekler. XFA desteği veri odaklıdır: ayrıştırıcı, template ve datasets paketlerini yapılandırır. XFA hesaplama betiklerini yürütmez veya dinamik XFA yerleşimlerini işlemez.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile 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. Sürümleri karşılaştırın ve bir lisans edinin.

Özellik başına lisans bayrağı yoktur. Bu, bir Pro sürümü yeteneğidir.

Genel API yüzeyi

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir/başarısız olur	Notlar
FormDataExtractor::extract	list<FormField> $fields	Her alanın adını ve değerini okur	XfdfData	—	Değeri boş olan alanları da içerir.
FormDataExtractor::toArray	list<FormField> $fields	Ad-değer dize eşlemesi oluşturur	array<string, string>	—	Sonraki yinelenen bir ad, öncekinin üzerine yazar.
FormDataExtractor::toXfdf	list<FormField> $fields, ?string $pdfHref = null	XfdfWriter::fromFields’e yetki devreder	string (XFDF XML)	—	Tek çağrıyla dışa aktarım için kolaylık yolu.
FormDataExtractor::extractNonEmpty	list<FormField> $fields	Değeri boş dize olan alanları atlar	XfdfData	—	—
FormDataExtractor::getEmptyFieldNames	list<FormField> $fields	Değeri ayarlanmamış alanların adlarını listeler	list<string>	—	extractNonEmpty’in tümleyeni.
XfdfWriter::fromFields	list<FormField> $fields, ?string $pdfHref = null	Ad-değer çiftlerini toplar, fromArray’e yetki devreder	string (XFDF XML)	—	—
XfdfWriter::fromArray	array<string, string> $data, ?string $pdfHref = null	Eşlemeyi XfdfData içine sarar, yetki devreder	string (XFDF XML)	—	—
XfdfWriter::fromXfdfData	XfdfData $data, ?string $pdfHref = null	XFDF’e dizileştirir; nokta gösterimli adlar hiyerarşik <field> öğeleri olarak yuvalanır	string (XFDF XML)	—	XML 1.0’da geçersiz denetim karakterlerini kaldırır; davranış sözleşmesine bakın.
XfdfParser::parse	string $xfdfXml	XML’i XXE’ye karşı güvenli biçimde yükler ve alanları nokta gösterimine düzleştirir	XfdfData	InvalidArgumentException	10 MiB giriş üst sınırı; ad alanlı ve ad alansız kökleri kabul eder.
XfdfParser::parseFile	string $filePath	Yolu çözer, dosyayı okur, parse’a yetki devreder	XfdfData	InvalidArgumentException	Eksik, dosya olmayan veya okunamayan yollar hata oluşturur.
XfaParser::parse	string $pdfData	İşaretçi denetimi, XML çıkarımı, paket ayrıştırma	XfaFormData	InvalidArgumentException, XfaParseException	/XFA işaretçisi yoksa hata değil, boş bir sonuç döner.
XfaParser::hasXfa	string $pdfData	Baytları /XFA işaretçisi için tarar	bool	—	Bayt işaretçisi taraması; belirtecin herhangi bir oluşumu eşleşir.
XfaParser::extractXfaXml	string $pdfData	XFA işaretçileri için akış taraması, ardından doğrudan <xdp:xdp> araması	string (XFA XML veya '')	RuntimeException (bildirilmiş)	Girişin en fazla ilk 50 MiB’ını tarar.
XfaParser::parseXml	string $xml	template ve datasets paketlerini çıkarır, <field> öğelerini ayrıştırır	XfaFormData	XfaParseException	DOM yüklemesinden önce uygulanan 10 MiB XML üst sınırı.
FormDataBinder::bind	list<FormField> $fields, XfdfData $data	Bağlı değerlerle yeni FormField örnekleri oluşturur	FormDataBindResult	—	Orijinaller asla değiştirilmez; onay kutuları Yes/Off değerine normalleştirilir.
FormDataBinder::fromXfdf	list<FormField> $fields, string $xfdfXml	XFDF’i ayrıştırır, ardından bağlar	FormDataBindResult	InvalidArgumentException	Hata modları XfdfParser::parse’ınkilerdir.
FormDataBinder::fromArray	list<FormField> $fields, array<string, string> $data	Eşlemeyi XfdfData içine sarar, ardından bağlar	FormDataBindResult	—	—
FormDataBindResult	isFullyBound, hasNoUnmatchedKeys, boundCount, fieldCount; readonly fields, boundFieldNames, unmatchedDataKeys, unboundFieldNames	Değişmez bağlama tanılamaları	yönteme göre	—	isFullyBound, sıfır eşleşmeyen anahtar ve sıfır bağlanmamış alan gerektirir.
XfdfData	hasField, getValue, count, isEmpty, getFieldNames, withField, withoutField, merge; readonly fields	Değişmez ad-değer kabı	yönteme göre	—	with* ve merge yeni örnekler döndürür; merge, argümanın değerlerini tercih eder.
XfaFormData	getField, hasField, count, fieldNames; readonly fields, templateXml, datasetsXml	Değişmez XFA ayrıştırma sonucu	yönteme göre	—	Gidiş-dönüş için ham template ve datasets paket XML’ini taşır.
XfaFormField	readonly name, type, value, required, caption, options	Değişmez tek alan kaydı	—	—	type, şunlardan biridir: text, numeric, date, choice, button, signature.
XfaPacket	enum durumları Template, Datasets, Config, LocaleSet, ConnectionSet, Form; xmlNamespace()	Dizeyle desteklenen paket numaralandırması	xmlNamespace()’ten string	—	Ad alanı URI’leri XFA Specification 3.3’ü izler.

public static function extract(array $fields): XfdfData
public static function toArray(array $fields): array
public static function toXfdf(array $fields, ?string $pdfHref = null): string
public static function extractNonEmpty(array $fields): XfdfData
public static function getEmptyFieldNames(array $fields): array

public static function fromFields(array $fields, ?string $pdfHref = null): string
public static function fromArray(array $data, ?string $pdfHref = null): string
public static function fromXfdfData(XfdfData $data, ?string $pdfHref = null): string

public static function parse(string $xfdfXml): XfdfData
public static function parseFile(string $filePath): XfdfData

public function parse(string $pdfData): XfaFormData
public function hasXfa(string $pdfData): bool
public function extractXfaXml(string $pdfData): string
public function parseXml(string $xml): XfaFormData

public static function bind(array $fields, XfdfData $data): FormDataBindResult
public static function fromXfdf(array $fields, string $xfdfXml): FormDataBindResult
public static function fromArray(array $fields, array $data): FormDataBindResult

İstisnalar

• NextPDF\Pro\Form\Exception\XfaParseException, RuntimeException’ı genişletir — XFA yükü bir XfaFormData’ya ayrıştırılamaz. Alt sınıflama bilinçlidir: mevcut catch (RuntimeException $e) çağrı yerleri çalışmaya devam eder.
• SPL InvalidArgumentException — XfdfParser’a boş, aşırı büyük, hatalı biçimli veya XFDF olmayan giriş; XfaParser::parse’a boş PDF girişi; XfdfParser::parseFile’da okunamayan yollar.

Davranış sözleşmesi

AcroForm çıkarımı. FormDataExtractor, geçirdiğiniz alan listesini gezer ve her alanın adını ve değerini okur. extract bir XfdfData döndürür; toArray düz bir ad-değer dize eşlemesi döndürür. extractNonEmpty, değeri boş dize olan alanları bırakır; getEmptyFieldNames tümleyen ad listesini döndürür. Çıkarım, giriş alanlarını asla değiştirmez.

XFDF yazma. XfdfWriter, ISO 19444-1:2019 yapısına uygun bir belge üretir. Çıktı, XFDF XML bildirimiyle ve Adobe XFDF ad alanında (http://ns.adobe.com/xfdf/) xml:space="preserve" içeren bir xfdf köküyle başlar. Null olmayan bir pdfHref, kaynak PDF’e geri başvuran bir <f href="..."/> başvurusu yayar. Nokta gösterimli alan adları (örneğin address.city) hiyerarşik bir <field> öğe ağacına yuvalanır. Değerler ve öznitelikler, beş XML meta karakterini kaçış karakterine çevirir. Alan adları, değerler ve pdfHref, iyi biçimlilik için ayrıca normalleştirilir: XML 1.0’ın yasakladığı C0 denetim karakterleri kaldırılırken TAB, LF ve CR korunur. Bu normalleştirme tasarım gereği kayıplıdır; böylece yazıcı, çağıranın sağladığı baytlardan bağımsız olarak her zaman iyi biçimlendirilmiş, yeniden ayrıştırılabilir XFDF yayar.

XFDF okuma. XfdfParser, hem ad alanlı hem de ad alansız xfdf köklerini kabul eder ve kök adını büyük/küçük harfe duyarsız eşleştirir; çünkü bazı üreticiler büyük harfli bir kök öğe yayar. Hiyerarşik <field> ağaçları, nokta gösterimli adlara geri düzleşir; böylece yazma ve okuma gidiş-dönüşü tamamlar. Tüm XML yüklemesi ağ erişimini ve harici varlık çözümlemesini devre dışı bırakır. parseFile, aynı ayrıştırmanın önüne yol çözümlemesi ve okunabilirlik denetimleri ekler.

Veri bağlama. FormDataBinder::bind, veri anahtarlarını alan adlarıyla eşleştirir. FormField değişmez olduğundan, bağlama güncellenmiş değerlerle yeni örnekler oluşturur; orijinaller asla değiştirilmez. Sonuç, üç tanılama kümesi bildirir: bağlanan alan adları, eşleşen alanı olmayan veri anahtarları ve hiçbir veri almayan alanlar. Onay kutusu değerleri, ISO 32000-2:2020, 12.7.5.2.3’ün açık/kapalı durum modeline normalleştirilir: büyük/küçük harfe duyarsız yes, true, 1 ve on değerleri Yes’e eşlenir; diğer her değer Off’a eşlenir.

XFA veri çıkarımı. XfaParser::parse, ham PDF baytlarını kabul eder. Önce /XFA işaretçisini tarar; işaretçi yoksa boş bir XfaFormData döndürür. Ardından çıkarım iki strateji dener: XFA XML göstergeleri için stream…endstream bloklarının taranması, sonra bir <xdp:xdp> belgesi için doğrudan arama. Tek bir xdp:xdp parçası olduğu gibi döndürülür; birden çok parça, sentezlenmiş bir xdp:xdp zarfında birleştirilir. parseXml, template ve datasets paketlerini çıkarır ve her template <field> öğesini bir XfaFormField’a ayrıştırır: name özniteliği zorunludur, tür alanın UI alt öğesinden türetilir, zorunluluk bayrağı nullTest değeri error olarak ayarlanmış bir validate öğesinden türetilir ve seçim seçenekleri items alt öğelerinden gelir.

XFA desteği veri odaklıdır. Ayrıştırıcı, template ve datasets paketlerini yapılandırır. XFA hesaplama betiklerini yürütmez, dinamik XFA yerleşimlerini işlemez veya her paket türünde gidiş-dönüş yapmaz. Buna güvenmeden önce ayrıştırıcıyı kendi belirli belge kümenizle doğrulayın.

Uç durumlar ve hata modları

• XfdfParser::parse(''), InvalidArgumentException oluşturur. 10 MiB üzerindeki giriş, üst sınırı belirten bir InvalidArgumentException oluşturur.
• Hatalı biçimli XML, toplanan libxml iletilerini taşıyan bir InvalidArgumentException oluşturur. Kökü xfdf olmayan, iyi biçimlendirilmiş bir belge hata oluşturur ve gerçek kök öğeyi adlandırır.
• <fields> öğesi olmayan bir XFDF belgesi boş bir XfdfData’ya ayrıştırılır; bu bir hata değildir.
• name özniteliği olmayan alan öğeleri hem XFDF hem de XFA ayrıştırmasında atlanır. <value> alt öğesi olmayan bir XFDF alanı hiçbir giriş katmaz.
• XfaParser::parse(''), InvalidArgumentException oluşturur. /XFA işaretçisi olmayan ya da XFA XML’i bulunamayan bir PDF, hata oluşturmak yerine boş bir XfaFormData döndürür.
• hasXfa bir bayt işaretçisi taramasıdır: dosyadaki herhangi bir /XFA belirteci, kullanılmayan bir nesnedeki dahil, eşleşir. Sonraki çıkarım adımı, kullanılabilir XML’in var olup olmadığına karar verir.
• XFA çıkarımı, PDF bayt dizisinin en fazla ilk 50 MiB’ını inceler; bu sınırın ötesindeki içerik taranmaz.
• 10 MiB üzerindeki XFA XML’i, herhangi bir DOM ağacı oluşturulmadan önce XfaParseException oluşturur. Hatalı biçimli XFA XML’i, libxml iletileriyle birlikte XfaParseException oluşturur.
• Onay kutusu normalleştirmesi, tanınmayan değerleri asla geçirmez; kabul edilen açık (on) biçimlerin dışındaki her şey Off değerine eşlenir.
• Yazıcının denetim karakteri kaldırması kayıplıdır: adlardaki, değerlerdeki veya pdfHref’teki XML 1.0’da geçersiz C0 baytları, çıktı iyi biçimlendirilmiş kalsın diye atılır. TAB, LF ve CR korunur.
• Tüm XML ayrıştırması, harici varlık çözümlemesini ve ağ erişimini devre dışı bırakır (XXE’ye karşı güvenli).
• Bu modül hiçbir kriptografik işlem gerçekleştirmez; FIPS modu davranışını değiştirmez.

Uygunluk

Davranış	Başvuru	Durum
Etkileşimli form / alan sözlüğü modeli	ISO 32000-2:2020, 12.7	Hizalı (ürün temelli)
Onay kutusu açık/kapalı durum normalleştirmesi (Yes/Off)	ISO 32000-2:2020, 12.7.5.2.3	Hizalı; madde bu sayfanın atıf kaydında belirtilmiştir
XFDF veri değişim yapısı	ISO 19444-1:2019	Hizalı (ürün temelli)
XFA paket adları ve ad alanı URI’leri	XFA Specification 3.3	Hizalı (ürün temelli)

Yazım sırasında kullanılabilir olan RAG derlemi ISO 19444-1:2019’u, XFA Specification’ı veya W3C XML 1.0’ı içermez; bu nedenle bu hizalama beyanları, madde atıflı değil, kaynak açıklamalarına ve testlere dayalı ürün temellidir. Bu beyanlar, başvurulan belgelere karşı yeteneği tanımlar. NextPDF hiçbir uygunluk sertifikasyonuna sahip değildir ve bir maddenin desteklenmesi bir sertifikasyon beyanı değildir.

Geliştirme notları

• XfaParser dışındaki her giriş noktası statiktir. XfaParser örneklenebilir ve durumsuzdur; tek bir örnek belgeler arasında güvenle yeniden kullanılabilir.
• Amaçlanan gidiş-dönüş şudur: Core form okuyucu FormField değerleri üretir; FormDataExtractor veya XfdfWriter bunları dizileştirir; XfdfParser veriyi geri okur; FormDataBinder bunu bir alan listesine uygular. Hiyerarşik adlar, nokta gösterimi aracılığıyla gidiş-dönüşü atlatır.
• Bir doldurma işlemini kabul etmeden önce bir XFDF veri dosyası ile gözden geçirilmiş bir PDF şablonu arasındaki sapmayı saptamak için FormDataBindResult tanılamalarını (isFullyBound, unmatchedDataKeys, unboundFieldNames) kullanın.
• XfdfData bir değer nesnesidir: withField, withoutField ve merge yeni örnekler döndürür. Anahtar çakışmalarında merge, argümanın değerlerini tercih eder.
• XfaFormData, ham template ve datasets paket XML’ini (templateXml, datasetsXml) saklar; böylece alan modelinin kapsamadığı paketleri sonradan işleyebilirsiniz.
• Bu modül, AcroForm sözlüklerini PDF baytlarından kendisi ayrıştırmaz; Core form okuyucunun ürettiği alanları tüketir. Yalnızca XfaParser ham PDF içeriği üzerinde çalışır.

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 (runbook) dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Form — yetenek genel bakışı
• Interop — Derinlemesine başvuru
• Core Form modülü