Belgeye görsel gömme

Bir bakışta

Bir raster görseli açıkça belirttiğiniz bir genişlikle mutlak bir konuma yerleştirin. Yüksekliği belirtmezseniz NextPDF bunu kaynak en boy oranından türetir. Bu reçete examples/07-images.php dosyasını temel alır. JPEG, PNG, GIF, BMP, WebP ve AVIF dosyalarını kullanabilirsiniz.

NextPDF, görseli bir ISO 32000-2 görsel XObject olarak gömer. Görsel sözlüğü genişliği, yüksekliği ve bileşen başına bit sayısını açıkça belirtir.

Kurulum

composer require nextpdf/core:^3

Buradaki image() API’si Core’un bir parçasıdır. Mevcut bir dosyayı gömmek için başka hiçbir şeye ihtiyacınız yoktur. Dayanak alınan örnek, GD ile bir test görseli oluşturduğu için ext-gd gerektirir. API, 1.0.0 sürümünden bu yana kararlıdır ve 8.1–8.4 backport matrisinde çalışır.

Kavramsal genel bakış

image($file, x, y, width, height) dosyayı görsel kayıt defteri üzerinden yükler, kodunu çözer ve yerleştirir. Kayıt defteri, kod çözme işleminden önce yolu doğrular. NUL baytı içeren veya URL şemasına (scheme://…) benzer görünen her yolu reddeder. image() yalnızca yerel dosyaları okur; hiçbir zaman uzak bir URL’yi okumaz. Kayıt defteri ayrıca pozitif olmayan bir width veya height değerini reddeder.

Yerleştirme, görselin birim karesini hedef dikdörtgene eşlemek için geçerli dönüşüm matrisini kullanır. ISO 32000-2 §8.8, bu yerleştirme için cm operatörünün bir q/Q çifti içinde kullanılacağını belirtir; böylece dönüşüm yalıtılmış kalır. Kodu çözülen raster, bir görsel XObject hâline gelir. Bunun BitsPerComponent değeri zorunludur ve 1, 2, 4, 8 veya 16’dan biri olmalıdır (§8.9.5).

API yüzeyi

API yüzeyi, PHPDoc’tan üretilir. Bu reçete tek bir yöntem kullanır:

image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null): static — yerel bir raster görseli gömer ve yerleştirir. Kaynak en boy oranını korumak için height değerini belirtmeyin. URL şeması içeren yolları, NUL baytlı yolları ve pozitif olmayan boyutları bir PageLayoutException ile reddeder.

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

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

// Absolute position; height inferred from the source aspect ratio.
$doc->image(__DIR__ . '/logo.png', x: 15, y: 30, width: 80);

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/images.pdf');

Kod örneği — üretim

Test düzeneğine hazır bu eksiksiz örnek, GD ile belirlenimci bir test görseli oluşturur; böylece reçete kendi içinde bağımsız kalır. NEXTPDF_COOKBOOK_OUTPUT değişkenini dikkate alır ve kendi tarafından ek entropi üretmez.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

if (!\extension_loaded('gd')) {
    fwrite(STDERR, "ext-gd required for the self-contained test image\n");
    exit(1);
}

// Build a deterministic test image (fixed pixels — no entropy).
$imgPath = \tempnam(\sys_get_temp_dir(), 'npf') . '.png';
$img = \imagecreatetruecolor(200, 100);
if ($img === false) {
    fwrite(STDERR, "GD imagecreatetruecolor failed\n");
    exit(1);
}
$bg = (int) \imagecolorallocate($img, 30, 58, 138);
$fg = (int) \imagecolorallocate($img, 255, 255, 255);
\imagefilledrectangle($img, 0, 0, 199, 99, $bg);
\imagestring($img, 5, 40, 40, 'NextPDF Image', $fg);
\imagepng($img, $imgPath);
\imagedestroy($img);

try {
    $doc = Document::createStandalone();
    $doc->setTitle('Image Embedding');
    $doc->addPage();

    $doc->setFont('helvetica', 'B', 18);
    $doc->cell(0, 12, 'Image Embedding', newLine: true);
    $doc->ln(5);

    // Absolute placement; width fixed, height from aspect ratio.
    $doc->image($imgPath, x: 15, y: 50, width: 80);
    // Same image, narrower — scaled down by the CTM, not re-decoded.
    $doc->image($imgPath, x: 15, y: 105, width: 40);

    $out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/images.pdf';
    $doc->save($out);
    echo "Created images.pdf\n";
} finally {
    @\unlink($imgPath);
}

Sınır durumlar ve dikkat edilecek noktalar

Uzak URL’ler desteklenmez. scheme://… ile eşleşen bir yol, bir PageLayoutException ile reddedilir. Önce kaynağı yerel bir dosyaya indirin, ardından o yolu geçirin. Yükleyici, sizin yerinize ağ üzerinden veri getirmez. Bu, kasıtlı bir sunucu tarafı istek sahteciliği (SSRF) korumasıdır.
Pozitif olmayan boyutlar istisna fırlatır. Bir width <= 0 veya height <= 0 değeri verildiğinde PageLayoutException fırlatılır. Doğal boyutu kullanmak için 0 geçirmek yerine bağımsız değişkeni belirtmeyin.
NUL baytlı yol reddedilir. \0 içeren bir yol reddedilir. Bu, null bayt enjeksiyonu içeren yollara karşı koruma sağlar. Kullanıcının sağladığı dosya adlarını doğrulayın.
En boy oranı. Orantılı olarak ölçeklemek için yalnızca width veya yalnızca height değerini geçirin. Her iki değeri de geçirmek görselin oranını bozabilir.
Aynı dosyanın iki kez gömülmesi. Dönüşüm matrisi aracılığıyla ölçeklemek için tek bir yolu yeniden kullanın. Motor, aynı baytların kodunu yeniden çözmez. Dosyaları çoğaltmak yerine yolu yeniden kullanmayı tercih edin.

Performans

Kod çözme maliyeti kaynak piksel sayısıyla orantılıdır; bu nedenle orta boyutlu bir fotoğrafa izin vermek için bütçe 96 MB’tır. Aynı yolu yeniden yerleştirmenin maliyeti azdır: ikinci bir kod çözme işlemi değil, fazladan bir Do ve bir cm. Genişliğe göre küçültmek, saklanan pikselleri azaltmaz. Belge boyutu önemliyse, büyük kaynak görselleri önceden yeniden boyutlandırın.

Güvenlik notları

URL şemalarının ve NUL baytlarının reddedilmesi, SSRF ve yol enjeksiyonuna karşı koruma sağlar. image() kandırılarak http://… adresinden veri getirmeye veya null bayttan sonrasını işlemeye zorlanamaz. Yine de kullanıcının sağladığı dosya adlarını güvenilmez olarak değerlendirin. image() çağrısından önce bunları izin verilen bir temel dizine göre çözümleyin. Dosya kullanıcı tarafından yüklendiğinde, görsel kod çözme işlemi saldırganın etkileyebildiği baytlar üzerinde çalışır. Girdi boyutunu sınırlayın ve kod çözmeyi yalıtılmış bir iş süreci içinde yapmayı değerlendirin.

Uygunluk

İfade	Belirtim	Madde
Bir görsel sözlüğü, genişliği, yüksekliği ve bileşen başına bit sayısını açıkça belirtir.	ISO 32000-2	§8.9.5
`BitsPerComponent` zorunludur ve 1, 2, 4, 8 veya 16’dır.	ISO 32000-2	§8.9.5
Bir görsel, `cm` operatörüyle bir `q`/`Q` çifti içinde yerleştirilir.	ISO 32000-2	§8.8

Yeniden üretilebilirlik profili — yapısal. Görsel baytları, sabit bir kaynak için belirlenimcidir. Kaydedilen her belge yine de bir fragman /ID değeri ve tarih atomları taşır; bu nedenle test düzeneği bunları çıkarır ve qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu reçete, NextPDF uygulamasının yapıyı nasıl ürettiğini açıklar. Kapsamlı bir ISO 32000-2 uygunluk iddiasında bulunmaz.

Ticari bağlam

Uygulanabilir değil. Raster görsel gömme, herhangi bir Premium kısıtlamasına tabi olmayan bir Core yeteneğidir.