İçeriği yerleştirmeden önce yerleşim kutularını inceleyin

Bir bakışta

İçeriği yerleştirmeden önce belgenin geçerli yerleşim geometrisini okuyun. Bu tarif; sayfa kutusunu, kenar boşluklarını, yazılamayan bölgeleri ve geçerli imleci okur. Böylece yerleştirme mantığınız tahmini koordinatlar yerine gerçek sayıları kullanabilir. Tarif, examples/34-inspect-layout-boxes.php dosyası ve buna ait tests/Cookbook/Php/InspectLayoutBoxesRecipeTest.php test koşumu tarafından desteklenir.

Kurulum

composer require nextpdf/core:^3

Pro veya Enterprise paketine ihtiyacınız yoktur. Yerleşim sorgu yüzeyi Core’un bir parçasıdır ve PHP 8.1 ile 8.4 arasında çalışır.

Kavramsal genel bakış

Bir Portable Document Format (PDF) sayfasında sınır kutuları bulunur. Bunların en temel olanı, sayfa boyutunu tanımlayan dikdörtgen MediaBox’tur (ISO 32000-2 §7.7.3.3). İçerik, kullanıcı uzayında konumlandırılır. Varsayılan olarak kullanıcı uzayı sol alt köşeden başlar ve bir birim 1/72 inç’e eşittir (§8.3.2). NextPDF size yazar dostu bir sol üst görünüm sunar ve geometriyi salt okunur sorgu yöntemleriyle açığa çıkarır:

getPageWidth() / getPageHeight() — sayfa kutusu boyutları.
getMargins() — etkin Margin değer nesnesi (üst/sağ/alt/sol).
getPageRegions() — bildirilen yazılamayan bölgeler (PageRegion[]). Her biri, içerik yerleştirilemeyen değişmez bir dikdörtgendir.
getX() / getY() — yazar uzayındaki geçerli imleç.

Bunlar idempotent okumalardır. İçerik üretmez, imleci ilerletmez ve durumu değiştirmezler. Kalan dikey alanı hesaplamak için bunları kullanın, ardından yazmaya devam edip etmeyeceğinize ya da addPage() çağıracağınıza karar verin. Ayrıca bir bloğu, sabit kodlanmış bir kaydırma değeri kullanmak yerine yazılamayan bir bölgeye göre yerleştirebilirsiniz.

API yüzeyi

Uygulama programlama arabirimi (API) yüzeyi PHPDoc’tan türetilir. Ana giriş noktaları \NextPDF\Core\Concerns\HasPages ve HasLayout trait’lerinde yer alır:

Document::getPageWidth(): float / Document::getPageHeight(): float
Document::getMargins(): \NextPDF\ValueObjects\Margin
Document::getPageRegions(): array (list<\NextPDF\Layout\PageRegion>)
Document::addPageRegion(float $x, float $y, float $w, float $h): static
Document::getX(): float / Document::getY(): float

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();

$pageHeight = $doc->getPageHeight();
$margins = $doc->getMargins();
$cursorY = $doc->getY();

// Vertical space left before the bottom margin.
$remaining = $pageHeight - $margins->bottom - $cursorY;

// Geometry is in user-space units (PDF points; 1 pt = 1/72 in).
echo sprintf("Page height: %.2f pt\n", $pageHeight);
echo sprintf("Bottom margin: %.2f pt\n", $margins->bottom);
echo sprintf("Cursor Y: %.2f pt\n", $cursorY);
echo sprintf("Remaining: %.2f pt\n", $remaining);

Kod örneği — üretim

Bu bağımsız program, test koşumu altında çalışır. Şu dosyayı yansıtır: examples/34-inspect-layout-boxes.php. Sayfa geometrisini okur, alt bilgi için yazılamayan bir bölge bildirir ve her blok için veriye dayalı bir karar verir. Sonraki blok bir bölgeyle çakışacaksa veya alt kenar boşluğunu aşacaksa, çakışma yaratmak yerine bir sayfa ekler.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Layout Box Inspection Demo');
$doc->setLanguage('en');
$doc->addPage();

// Read the geometry (idempotent, no side effects). Values are in
// user-space units (PDF points; 1 pt = 1/72 in).
$pageWidth  = $doc->getPageWidth();
$pageHeight = $doc->getPageHeight();
$margins    = $doc->getMargins();

echo sprintf("Page box: %.2f x %.2f pt\n", $pageWidth, $pageHeight);
echo sprintf("Cursor start: (%.2f, %.2f)\n", $doc->getX(), $doc->getY());

// A 15 pt tall footer no-write zone across the text column.
$footerHeight = 15.0;
$footerTop    = $pageHeight - $margins->bottom - $footerHeight;
$doc->addPageRegion(
    $margins->left,
    $footerTop,
    $pageWidth - $margins->left - $margins->right,
    $footerHeight,
);

$blocks = [
    'Section 1. Each block measures the live cursor against the page box '
        . 'and any no-write region before it is placed.',
    'Section 2. The lowest Y at which any region starts is the hard floor '
        . 'for new content; crossing it forces a page break.',
    'Section 3. Reading geometry is idempotent — the query methods never '
        . 'advance the cursor, so they are safe in the placement loop.',
    'Section 4. This final block forces a second page when the column is '
        . 'already near the footer keep-out zone.',
];

$blockHeight = 42.0;
$pagesUsed   = 1;

foreach ($blocks as $index => $text) {
    $cursorY = $doc->getY();

    // Lowest Y a region starts at — the hard floor for new content.
    $regionFloor = $pageHeight - $margins->bottom;
    foreach ($doc->getPageRegions() as $region) {
        $regionFloor = min($regionFloor, $region->y);
    }

    if ($cursorY + $blockHeight > $regionFloor) {
        $doc->addPage();
        ++$pagesUsed;
        // A fresh page resets the region set; re-declare the footer zone.
        $footerTop = $doc->getPageHeight() - $doc->getMargins()->bottom - $footerHeight;
        $doc->addPageRegion(
            $doc->getMargins()->left,
            $footerTop,
            $doc->getPageWidth() - $doc->getMargins()->left - $doc->getMargins()->right,
            $footerHeight,
        );
    }

    $doc->setFont('helvetica', 'B', 12);
    $doc->cell(0, 8, 'Block ' . ($index + 1), newLine: true);
    $doc->setFont('helvetica', '', 11);
    $doc->multiCell(0, 7, $text);
    $doc->ln(6);
}

// The harness sets NEXTPDF_COOKBOOK_OUTPUT and runs this script under the
// semantic profile (validated by structural AST + metadata, not a byte hash).
$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false && $out !== '' ? $out : __DIR__ . '/inspect-layout-boxes.pdf');

echo sprintf("Pages used: %d (page breaks decided from layout geometry)\n", $pagesUsed);

Beklenen standart çıktı (STDOUT) aşağıdaki gibidir. Sayfa kutusu sayıları varsayılan A4 sayfa boyutunu yansıtır ve imleç, sol üst içerik başlangıç noktasından başlar:

Page box: 595.28 x 841.89 pt
Cursor start: (<x>, <y>)
Pages used: 2 (page breaks decided from layout geometry)

Uç durumlar ve dikkat edilecek noktalar

Sayfa var olmadan önce okuma. getPageWidth() ve getPageHeight() geçerli sayfayı yansıtır; bu nedenle bunları addPage() sonrasında çağırın. İlk sayfa eklenmeden önce, henüz eklemediğiniz bir sayfayı değil, varsayılan sayfa boyutu geometrisini döndürürler.
Bölgeler yazar uzayı dikdörtgenleridir. Bir PageRegiony, getY() ile tutarlı şekilde sol üstten ölçülen yazar mesafesidir. Bunu ham sol alt PDF koordinatlarıyla karıştırmayın.
Okumalar yan etkisizdir. Sorgu yöntemlerinin hiçbiri imleci ilerletmez veya içerik üretmez. Bunları sıkı bir döngü içinde çağırmak güvenlidir ve maliyetleri çok düşüktür.
Kenar boşlukları sayfa başına değişebilir. Daha sonraki bir sayfada farklı kenar boşlukları ayarlanırsa, ilk değeri önbelleğe almak yerine getMargins() değerini yeniden okuyun.
Bölgeler metni otomatik olarak yeniden akıtmaz. Yazılamayan bir bölge, otomatik bir metin kaydırma sınırı değil, uymanız gereken bir kısıttır. Tarif, açık çakışma denetimini gösterir. Serbest konumlandırılmış yazma işlemlerinde, motor içeriği kendiliğinden bir bölgenin dışına asla taşımaz.

Performans

Buradaki her yöntem bir özellik okumasıdır. Sabit zamanda, bellek ayırmadan ve giriş ya da çıkış yapmadan çalışır. Örnek, 1500 ms / 96 MB bütçesinin oldukça içinde kalan küçük, çok sayfalı bir belge oluşturur. Yeniden üretilebilirlik profili anlamsaldır, çünkü oluşturulan PDF, trailer /ID değerini ve oluşturma meta verilerini taşır. Örnekte asıl önemli olan, gözlemlenebilir geometri kararlarıdır; bu nedenle test koşumu, bu kararları bir bayt karması yerine yapısal bir soyut sözdizimi ağacı (AST) ve meta veri karşılaştırmasıyla doğrular.

Güvenlik notları

Veri yerleşimi ve PII azaltma önlemleri. Uygulanabilir değil. Tarif geometriyi okur ve çağıran tarafından sağlanan metni yerleştirir; bu nedenle yeni bir veri yolu eklemez. Yerleştirdiğiniz metne, diğer her yerde uygulayacağınız aynı en aza indirme yaklaşımını uygulayın.
Güvenli telemetri ve günlük temizleme. Örnek, geometri sayılarını ve sabit bir ilerleme satırını yazdırır. Belge metnini günlüğe kaydetmez.
Tehdit modeli. Uygulanabilir değil. Sorgu yüzeyi salt okunurdur ve hiçbir dış girdiyi ayrıştırmaz. Bir güven sınırı değildir.
FIPS modu davranışı. Uygulanabilir değil. Hiçbir kriptografik işlem çalışmaz.

Uygunluk

İfade	Spesifikasyon	Madde
Bir sayfa nesnesi, sınırlarını sınır kutuları (MediaBox) aracılığıyla tanımlar.	ISO 32000-2	§7.7.3.3
Sayfa dikdörtgeni, içerik sınırıdır.	ISO 32000-2	§7.7.3.3
Konumlar kullanıcı uzayında ölçülür; bir birim 1/72 inçtir.	ISO 32000-2	§8.3.2

Bu tarif, alıntılanan ISO 32000-2 sayfa kutusu ve kullanıcı uzayı maddelerinde tanımlanan geometriyi okur. Tam kapsamlı bir ISO 32000-2 uygunluğu öne sürmez. Yerleşim sorgu yüzeyi, alıntılanan maddelere dayanır.