NextPDF Connect ile görüntü gömme

Bir bakışta

NextPDF Connect ile bir PDF dosyasına görüntü gömün. Kaynak olarak sunucunun okuyabildiği bir dosya yolu veya satır içi bir base64 veri URI’si kullanın. Bunun için create_pdf, add_image ve output_pdf araçlarını kullanırsınız — bunların tümü Core araçlarıdır. NextPDF görüntüyü, Do operatörüyle boyanan bir görüntü XObject’i olarak çizer (ISO 32000-2 §8.9).

Kurulum

composer require nextpdf/server

Bir taşıma bağlantısı kurun. NextPDF, PNG, JPEG ve GIF raster biçimlerini destekler.

Kavramsal genel bakış

add_image bir source alır ve bunu şu sabit sırayla çözer:

Veri URI’si — data: ile başlayan bir dize. NextPDF, Multipurpose Internet Mail Extensions (MIME) türünü ve base64 yükünü ayrıştırır, yükü geçici bir dosyaya yazar, dosyayı gömer, ardından geçici dosyayı kaldırır.
Ham base64 — NextPDF uzun bir base64 dizesini çözer ve onu PNG olarak değerlendirir.
Dosya yolu — NextPDF diğer her şeyi, sunucu işleminin okuyabilmesi gereken bir dosya sistemi yolu olarak değerlendirir.

Görüntü, kullanıcı birimlerinde (varsayılan olarak milimetre) x/y konumunda görünür. Yalnızca width değerini iletin; NextPDF en boy oranını korumak için yüksekliği hesaplar. Hem width hem de height değerlerini ilettiğinizde NextPDF görüntüyü tam olarak bu boyutlara ölçekler. Gömülü nesne, sayfa içeriğine boyanan harici bir nesnedir (ISO 32000-2 §8.8).

API yüzeyi

Araç	Rol	Risk düzeyi
`create_pdf`	Oturumu açar	Güvenli
`add_image`	Yoldan veya veri URI’sinden bir görüntü gömer	Dikkat
`output_pdf`	PDF’yi oluşturur ve döndürür	Onay gerekli / inceleme (base64)

İlgili Araç kataloğu kayıtlı katalogdur. Kullanabileceğiniz araçlar, kurulu olan katmana bağlıdır.

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

create_pdf (A4 dikey, başlık) → document_id.
add_image; source mutlak bir yola ayarlanır; x, y, width değerleri verilir.
add_image; source bir data:image/png;base64,... URI’sine ayarlanır; width ve height değerleri açıkça belirtilir.
output_pdf → base64.

Kod örneği — üretim

Bir grafik oluşturma çıktısı veya ekran görüntüsü gibi, ana makinenin bellekte ürettiği bir görüntü için veri URI’si kullanın. Sunucuda zaten bulunan bir varlık için bir dosya yolu kullanın. Her zaman mutlak yollar kullanın. Göreli bir yol genellikle ana makinenin değil sunucunun çalışma dizinine göre çözülür. Devam etmeden önce, add_image yanıtının görüntünün beklenen sayfada yer aldığını bildirdiğini doğrulayın.

Sınır durumları ve tuzaklar

Yol bulunamadı. Eksik dosya yolu, görüntü bulunamadı hatası döndürür.
Desteklenmeyen biçim. NextPDF, SVG, BMP ve WebP biçimlerini reddeder. Önce görüntüyü dönüştürün.
Hatalı biçimlendirilmiş base64 / veri URI’si. Bozuk bir yük veya virgül ayırıcısı eksik olan bir veri URI’si, çözme hatası döndürür.
Aşırı büyük görüntü. Sayfadan büyük bir görüntü reddedilmez; kenardan kırpılır. width/height değerlerini, kenar boşlukları çıkarılmış sayfaya göre hesaplayın (A4 dikey 210×297 mm’dir).

Performans

Çıktı boyutu, görüntü içeriğiyle ölçeklenir. İki küçük görüntü genellikle 10–50 KB’dir. Görüntü gömme bütçesi, yalnızca metin için ayrılan bütçeden daha geniştir. Bu sayfa structural profilini kullanır.

Güvenlik notları

Dosya yolu modu, sunucunun dosya sisteminden sunucu işleminin ayrıcalıklarıyla okuma yapar. Ana makinenin iletebileceği yolları sınırlandırın. Güvenilmeyen çağıranların source değerini rastgele sunucu dosyalarına yönlendirmesine izin vermeyin. Base64 modu baytları satır içinde taşır, bu nedenle sunucu yolunun açığa çıkmasını önler.

Uyumluluk

İfade	Spesifikasyon	Madde	reference_id
Bir görüntü, `Do` tarafından boyanan bir görüntü XObject’idir.	ISO 32000-2	§8.9
Görüntüler, sayfa içeriğine boyanan harici nesnelerdir.	ISO 32000-2	§8.8

Ticari bağlam

Uygulanmaz — tüm araçlar Core’a dahildir.

Taşıma kullanılabilirliği

Taşıma	Kullanılabilir	Notlar
MCP (stdio)	Evet	Büyük base64 yükleri, stdio çerçevesini şişirir.
REST	Evet	Büyük varlıklar için multipart veya bir sunucu yolu tercih edin.
gRPC	Evet	Tekli çağrı; mesaj boyutu sınırları satır içi base64 için geçerlidir.

HITL risk düzeyi

create_pdf güvenli, add_image dikkat ve output_pdf onay gerekli düzeyindedir — base64 modunda inceleme düzeyine düşürülür. Yol modundaki okuma sunucu tarafındadır ve ayrıca kapı denetimine tabi değildir, bu nedenle bunu ilke katmanında sınırlandırın (HITL risk düzeyleri).

Onay kapısı JSON zarfı

Base64 çıktısı şudur:

{ "allowed": true }