Form

Bir bakışta

NextPDF Pro, etkileşimli form verilerini okur ve yazar: AcroForm alan değerleri, XFDF veri dosyaları ve XFA (XML Forms Architecture) şablonlarının taşıdığı veriler. Açık kaynaklı Core form okuyucusunu veri bağlama, çıkarım ve serileştirme ile tamamlar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) sürümünde sunulur ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Form, Pro sürümünün bir parçasıdır. Özellik başına ayrı bir lisans bayrağı yoktur.

Kurulum

composer require nextpdf/pro:^3

Form yeteneği geçerli bir NextPDF Pro lisansı gerektirir. Bkz. Kullanılabilirlik ve lisanslama.

Kavramsal genel bakış

Bir PDF etkileşimli formu — bazen AcroForm olarak adlandırılır — her alanı, ISO 32000-2 §12.7’de tanımlandığı gibi bir alan sözlüğünde saklar. NextPDF Pro, üç yetenek eklemek için Core form okuyucusunun üzerine kurulur:

• AcroForm gidiş-dönüşü. FormDataExtractor, ayrıştırılmış form alanlarından alan adı/değer çiftlerini okur ve bir XfdfData nesnesi veya düz bir name → value eşlemesi üretir. XfdfWriter, tersini yaparak bir XFDF belgesi oluşturur.
• XFDF okuma ve yazma. XFDF, ISO 19444-1:2019 tarafından tanımlanan, form değerleri için XML veri değişim biçimidir. XfdfParser, bir XFDF dosyasını yapılandırılmış veriye okur; XfdfWriter, alan değerlerini, kaynak PDF’e isteğe bağlı bir geri başvuruyla XFDF’e serileştirir.
• XFA veri çıkarımı. XfaParser, bir belgedeki XFA paketlerini konumlandırır, XML parçalarını birleştirir ve şablon ile veri kümeleri paketlerini yapılandırılmış alan verisine ayrıştırır.

XFA destek kapsamı

NextPDF Pro’daki XFA desteği, tam bir XFA işleme veya betik motoru değil, veri odaklıdır. Ayrıştırıcı, alan tanımlarını ve değerlerini okuyabilmeniz için şablon ve veri kümeleri paketlerini çıkarır ve yapılandırır. XFA form hesaplama betiklerini yürütmez, dinamik XFA yerleşimlerini işlemez veya her XFA paket türünü gidiş-dönüş işlemez. Belirli bir XFA form kümesi için ona güvenmeden önce ayrıştırıcıyı kendi belgelerinize karşı test edin. Tüm XML ayrıştırması, harici varlık yüklemesini devre dışı bırakır (XXE’ye karşı güvenli).

Neden bu şekilde çalışır

XFA desteği, bilinçli olarak işlemeyle değil veriyle sınırlandırılmıştır. ISO 32000-2, form sözlüğünün XFA girdisini PDF 2.0’da kullanımdan kaldırılmış olarak işaretler (§12.7). Tam bir XFA yerleşim ve betik motoru, çoğu iş yükünün artık ihtiyaç duymadığı eski bir yüzeyin peşinden giderdi. NextPDF Pro bunun yerine, kalıcı alan verisinin bulunduğu şablon ve veri kümeleri paketlerini çıkarır ve gerisini reddeder. Aynı duruş, form girdisi çoğu zaman güvenilmeyen taraflardan geldiği için XXE’siz ayrıştırmayı ve tarama tavanını yönlendirir. Bu, Pro form yüzeyini Core AcroForm modelinin ince, öngörülebilir bir uzantısı olarak tutar.

Tasarım arka planı: Doldurulabilir formdan dondurulmuş kayda: AcroForm doldurma ve düzleştirme.

API yüzeyi

Sınıf	Sorumluluk
FormDataExtractor	AcroForm alan değerlerini XfdfData veya bir dizi olarak çıkarır.
XfdfParser	Bir XFDF belgesini yapılandırılmış veriye ayrıştırır.
XfdfWriter	Alan değerlerini XFDF’e serileştirir, isteğe bağlı PDF başvurusu.
XfaParser	XFA şablon ve veri kümeleri paketlerini çıkarır ve ayrıştırır.
FormDataBinder	Bir veri eşlemesini form alanlarına geri bağlar.

Tam yöntem düzeyinde başvuru, Form derinlemesine başvurusunda yer alır.

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

use NextPDF\Pro\Form\FormDataExtractor;
use NextPDF\Pro\Form\XfdfWriter;

$values = FormDataExtractor::toArray($fields);
$xfdf   = XfdfWriter::fromFields($fields, 'invoice.pdf');

Kod örneği — Üretim

use NextPDF\Pro\Form\XfaParser;
use NextPDF\Pro\Form\Exception\XfaParseException;

try {
    $formData = (new XfaParser())->parse($pdfBytes);
    $logger->info('xfa.parsed', ['fields' => count($formData->fields)]);
} catch (XfaParseException $e) {
    $logger->warning('xfa.parse_failed', ['reason' => $e->getMessage()]);
}

Uç durumlar ve dikkat edilmesi gerekenler

• XfaParser, tarama tavanından büyük PDF girdisini, sınırsız veri okumak yerine reddeder.
• Bir belge hem etkileşimli hem de etkileşimli olmayan formlar taşıyabilir; çıkarım, uç alan sözlüklerini hedefler.
• XFDF, düz alan yapılarını gidiş-dönüş işler; derin iç içe alan hiyerarşileri açık işleme gerektirebilir.

Performans

Çıkarım ve serileştirme, form alanlarının sayısında doğrusaldır. XFA ayrıştırma maliyeti, gömülü XML paketlerinin boyutuyla ölçeklenir.

Güvenlik notları

Tüm XML ayrıştırması, XXE’yi önlemek için harici varlık çözümlemesini devre dışı bırakır. Güvenilmeyen kaynaklardan gelen XFDF ve XFA girdisini husumetli olarak değerlendirin ve ayrıştırılan alan kümesini bir belgeye geri bağlamadan önce doğrulayın.

Uygunluk

Davranış	Başvuru	Durum
Etkileşimli form / alan sözlüğü modeli	ISO 32000-2 §12.7	Hizalanmış (yorumlanarak)
XFDF veri değişim biçimi	ISO 19444-1:2019	Hizalanmış

Bu tablo, NextPDF Pro’nun karşı geliştirildiği belirtimleri kaydeder. Resmi bir sertifikasyon beyanı değildir.

Davranış sözleşmesi

• FormDataExtractor, ayrıştırılmış uç alan sözlüklerinden adı/değer çiftlerini okur ve bir XfdfData nesnesi veya düz bir name → value dizisi döndürür.
• XfdfParser, bir XFDF belgesini yapılandırılmış veriye ayrıştırır; XfdfWriter, alan değerlerini kaynak PDF’e isteğe bağlı bir geri başvuruyla XFDF’e serileştirir.
• XfaParser, XFA paketlerini konumlandırır, XML parçalarını birleştirir ve şablon ile veri kümeleri paketlerini yapılandırılmış alan verisine ayrıştırır. Tarama tavanından büyük PDF girdisini, sınırsız veri okumak yerine reddeder.
• XFA desteği veri odaklıdır: ayrıştırıcı, şablon ve veri kümeleri paketlerini çıkarır ve yapılandırır. XFA form hesaplama betiklerini yürütmez, dinamik XFA yerleşimlerini işlemez veya her XFA paket türünü gidiş-dönüş işlemez.
• Tüm XML ayrıştırması, harici varlık çözümlemesini devre dışı bırakır (XXE’ye karşı güvenli).

Enterprise sınır notu

Enterprise, Form davranışını değiştirmez. Enterprise, ayrı olarak belgelenen üst katman uyumluluk ve arşivsel özellikleri ekler; bunlar AcroForm gidiş-dönüşü, XFDF okuma/yazma veya XFA veri çıkarımı için gerekli değildir.

Core geri dönüşü / alternatifi

NextPDF Core’un açık kaynaklı form okuyucusu, form alanlarını okur. XFDF okuma/yazma, XFA veri çıkarımı ve alan bağlama Pro eklentileridir. Bkz. /modules/form/.

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 talep önekleri kapsam dışıdır.

Ayrıca bkz.

• Interop — harici sistemler için sürümlü form verisi DTO’ları.
• Core Form modülü — açık kaynaklı form okuyucusu.
• Form — Derinlemesine başvuru — Pro form sınıfları için yöntem düzeyinde başvuru.