Menyematkan gambar dalam dokumen

Sekilas pandang

Tempatkan gambar raster pada posisi absolut dengan lebar yang ditentukan secara eksplisit. Biarkan tinggi tidak diisi, dan NextPDF akan menghitungnya dari rasio aspek sumber. Resep ini mengikuti examples/07-images.php. Anda dapat menggunakan berkas JPEG, PNG, GIF, BMP, WebP, dan AVIF.

NextPDF menyematkan gambar sebagai XObject gambar ISO 32000-2. Kamus gambar menyatakan lebar, tinggi, dan bit per komponen secara eksplisit.

Pemasangan

composer require nextpdf/core:^3

API image() adalah bagian dari Core. Anda tidak memerlukan komponen lain untuk menyematkan berkas yang sudah ada. Contoh pendukungnya menghasilkan gambar uji dengan GD, sehingga memerlukan ext-gd. API ini stabil sejak 1.0.0 dan berjalan pada matriks backport 8.1–8.4.

Tinjauan konseptual

image($file, x, y, width, height) memuat berkas melalui registri gambar, mendekodenya, lalu menempatkannya. Registri memvalidasi jalur sebelum proses dekode. Registri menolak jalur apa pun yang mengandung bita NUL atau menyerupai skema Uniform Resource Locator (URL) (scheme://…). image() hanya membaca berkas lokal; tidak pernah mengambil URL jarak jauh. Registri juga menolak width atau height yang tidak positif.

Penempatan menggunakan matriks transformasi saat ini untuk memetakan persegi satuan gambar ke persegi panjang target. ISO 32000-2 §8.8 menetapkan operator cm di dalam pasangan q/Q untuk penempatan ini, sehingga transformasi tetap terisolasi. Raster yang telah didekodekan menjadi XObject gambar. BitsPerComponent wajib ada dan harus bernilai salah satu dari 1, 2, 4, 8, atau 16 (§8.9.5).

Permukaan API

Permukaan API dihasilkan dari PHPDoc. Resep ini menggunakan satu metode:

image(string $file, ?float $x = null, ?float $y = null, ?float $width = null, ?float $height = null): static — menyematkan dan menempatkan gambar raster lokal. Biarkan height tidak diisi untuk mempertahankan rasio aspek sumber. Metode ini menolak jalur berskema URL, jalur berbita NUL, dan dimensi yang tidak positif dengan PageLayoutException.

Contoh kode — Mulai cepat

<?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');

Contoh kode — Produksi

Contoh lengkap yang siap digunakan oleh harness ini menghasilkan gambar uji deterministik dengan GD, sehingga resep tetap mandiri. Contoh ini mengikuti NEXTPDF_COOKBOOK_OUTPUT dan tidak menetapkan entropinya sendiri.

<?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);
}

Kasus tepi & hal yang perlu diperhatikan

Tidak ada URL jarak jauh. Jalur yang cocok dengan scheme://… ditolak dengan PageLayoutException. Unduh aset ke berkas lokal terlebih dahulu, lalu berikan jalur tersebut. Pemuat tidak mengambil data dari jaringan untuk Anda. Ini adalah perlindungan Server-Side Request Forgery (SSRF) yang disengaja.
Dimensi tidak positif memicu kesalahan. width <= 0 atau height <= 0 memunculkan PageLayoutException. Untuk menggunakan ukuran alami, biarkan argumen tidak diisi alih-alih memberikan 0.
Jalur berbita NUL ditolak. Jalur yang mengandung \0 ditolak. Ini melindungi terhadap jalur poison-null-byte. Validasi nama berkas yang diberikan oleh pengguna.
Rasio aspek. Berikan hanya width atau hanya height untuk menskalakan secara proporsional. Memberikan kedua nilai dapat mendistorsi gambar.
Berkas yang sama disematkan dua kali. Gunakan kembali satu jalur untuk menskalakan melalui matriks transformasi. Mesin tidak mendekode ulang bita yang identik. Utamakan penggunaan kembali jalur daripada menduplikasi berkas.

Kinerja

Biaya dekode sebanding dengan jumlah piksel sumber; karena itu, anggarannya adalah 96 MB untuk mengakomodasi foto berukuran sedang. Menempatkan jalur yang sama lagi hanya menambah biaya kecil: satu Do tambahan ditambah satu cm, bukan dekode kedua. Memperkecil gambar berdasarkan lebar tidak mengurangi piksel yang tersimpan. Ubah ukuran gambar sumber yang besar terlebih dahulu jika ukuran dokumen menjadi pertimbangan.

Catatan keamanan

Penolakan skema URL dan bita NUL melindungi terhadap SSRF dan injeksi jalur. image() tidak dapat ditipu untuk mengambil http://… atau menelusuri melewati bita NUL. Meski demikian, perlakukan nama berkas yang diberikan pengguna sebagai tidak tepercaya. Selesaikan nama tersebut terhadap direktori dasar yang diizinkan sebelum Anda memanggil image(). Untuk berkas yang diunggah pengguna, dekode gambar berjalan pada bita yang dapat dipengaruhi penyerang. Batasi ukuran masukan dan pertimbangkan untuk mendekode dalam worker terisolasi.

Kesesuaian

Pernyataan	Spesifikasi	Klausa
Kamus gambar menentukan lebar, tinggi, dan bit per komponen secara eksplisit.	ISO 32000-2	§8.9.5
`BitsPerComponent` wajib ada dan bernilai 1, 2, 4, 8, atau 16.	ISO 32000-2	§8.9.5
Gambar ditempatkan melalui operator `cm` di dalam `q`/`Q`.	ISO 32000-2	§8.8

Profil reproduktibilitas — struktural. Bita gambar bersifat deterministik untuk sumber yang sama. Setiap dokumen yang disimpan tetap menyertakan /ID trailer dan atom tanggal, sehingga harness menghapus keduanya dan membandingkan struktur qpdf yang dinormalisasi. Resep ini menjelaskan cara NextPDF menghasilkan struktur tersebut. Resep ini tidak membuat klaim kesesuaian ISO 32000-2 secara menyeluruh.

Konteks komersial

Tidak berlaku. Penyematan gambar raster adalah kemampuan Core dan tidak dibatasi oleh Premium.