ValueObjects: alan ilkelleri + birimler

Bir bakışta

ValueObjects modülü, motor genelinde kullanılan değişmez geometri ilkellerini sağlar: PageSize, Dimension, Position, Margin ve Unit enum’u. Her biri bir final readonly sınıftır. Bir örneği serbestçe paylaşabilirsiniz ve her dönüşüm yeni bir örnek döndürür.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

Dört değer nesnesinin tümü final readonly niteliğindedir. float koordinatlarını saklarlar ve hiçbir değiştirici sunmazlar; dönüşüm yöntemleri, yeni bir örneği adlandırılmış argümanlarla yeniden oluşturur. Bunları önbelleğe alabilir, belgeler arasında aktarabilir ve savunmacı kopyalama olmadan worker süreçleri arasında paylaşabilirsiniz.

PageSize genişlik, yükseklik (punto cinsinden; 1 pt = 1/72 inç) ve bir ad saklar. Statik fabrika yöntemleri, Uluslararası Standardizasyon Örgütü (ISO) 216 A serisini (A0–A6), ISO 216 B serisini (B0–B5) ve Kuzey Amerika boyutlarını (Letter, Legal, Tabloid) kapsar. A/B ölçüleri, ISO 216 tarafından tanımlanan kesilmiş kâğıt boyutu serisini izler. fromName() adları büyük/küçük harfe duyarsız biçimde çözer ve bilinmeyen bir ad için PageLayoutException fırlatır. landscape() ve portrait() yönelim çeşidini, sayfa zaten o yönelimdeyse self döndürür. toDimension() sayfa boyutunu punto cinsinden bir Dimension değerine dönüştürür.

Dimension genişlik, yükseklik ve bir Unit saklar. Fabrika yöntemleri (fromMillimeters(), fromPoints(), fromInches()) seçilen birimde bir ölçü oluşturur. toPoints() ve toMillimeters() birimleri dönüştürür; ölçü zaten punto cinsindeyse toPoints() self döndürür. withWidth() ve withHeight() boyutu değiştirilmiş bir kopya döndürür. Dönüşümler tam çarpanlar kullanır: milimetre başına 72/25.4 punto, santimetre başına 72/2.54 ve inç başına 72.

Position, Taşınabilir Belge Biçimi (PDF) kullanıcı uzayında iki boyutlu bir noktadır (x, y). origin() (0, 0) değerini döndürür. translate(dx, dy) kaydırılmış bir kopya döndürür. withX() / withY() ilgili ekseni değiştirilmiş bir kopya döndürür.

Margin top, right, bottom ve left değerlerini tutar. Fabrika yöntemleri uniform() (tüm kenarlarda aynı değer), symmetric(vertical, horizontal) ve zero() şeklindedir.

Unit, dize destekli bir enum’dur: Point (pt), Millimeter (mm), Centimeter (cm) ve Inch (in). toPointFactor() puntoya dönüştürme çarpanını döndürür.

API yüzeyi

Sembol	Tür	Temel üyeler
NextPDF\ValueObjects\PageSize	final readonly sınıf	$width, $height, $name; fabrikalar A0–A6, B0–B5, Letter, Legal, Tabloid; fromName(), landscape(), portrait(), toDimension()
NextPDF\ValueObjects\Dimension	final readonly sınıf	$width, $height, $unit; fromMillimeters(), fromPoints(), fromInches(), toPoints(), toMillimeters(), withWidth(), withHeight()
NextPDF\ValueObjects\Position	final readonly sınıf	$x, $y; origin(), translate(), withX(), withY()
NextPDF\ValueObjects\Margin	final readonly sınıf	$top, $right, $bottom, $left; uniform(), symmetric(), zero()
NextPDF\ValueObjects\Unit	string enum	Point, Millimeter, Centimeter, Inch; toPointFactor()

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

Geometri ilkellerini oluşturmak için fabrika yöntemlerini kullanın.

<?php

declare(strict_types=1);

use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;
use NextPDF\ValueObjects\Position;

$page = PageSize::A4();                       // 595.276 x 841.890 pt
$margin = Margin::uniform(18.0);              // 18 pt all sides
$origin = Position::origin()->translate(72.0, 72.0); // 1 inch in from corner

Kod örneği — üretim

Birimleri dönüştürün, yönelim türetin ve kenar boşluklarını yapılandırmaya aktarın.

<?php

declare(strict_types=1);

use NextPDF\Core\Config;
use NextPDF\ValueObjects\Dimension;
use NextPDF\ValueObjects\Margin;
use NextPDF\ValueObjects\PageSize;

// A label sized in millimeters, resolved to points for the engine.
$label = Dimension::fromMillimeters(width: 100.0, height: 150.0)->toPoints();

$page = PageSize::A4()->landscape();   // swap to width >= height
$margin = Margin::symmetric(vertical: 20.0, horizontal: 15.0);

$config = (new Config())
    ->withPageSize($page)
    ->withMargins($margin);

// $label->width / $label->height are now in points for downstream layout.

Sınır durumları ve tuzaklar

• Tüm ölçüler, bir Dimension’ı açık bir Unit ile sağlamadığınız sürece punto kullanır. Config kenar boşlukları varsayılan olarak punto kullanır.
• PageSize::landscape() / portrait() yönelim zaten eşleştiğinde aynı örneği döndürür; tahsis yapılmaz ve kimlik korunur.
• PageSize::fromName() büyük/küçük harfi yok sayar, ancak yalnızca adlandırılmış fabrika yöntemlerini çözer. Bilinmeyen bir ad varsayılan bir boyuta düşmez; PageLayoutException fırlatır.
• Dimension::toPoints() çağrısı self döndürür: birim zaten Point olduğunda yeni bir nesne oluşturulmaz; yeni bir nesne varsaymayın.
• Bu nesneler ham float değerlerini tutar ve hiçbir aralık doğrulaması uygulamaz. Oluşturma sırasında negatif veya sıfır ölçüleri kabul ederler. Geometri geçerliliğini bu nesneler değil, yerleşim ve yazıcı katmanları zorunlu kılar.
• Kayan noktalı dönüşümler tam rasyonel çarpanlar kullanır (72/25.4, 72/2.54); yeniden üretilebilir çıktıyı kararlı tutmak için yalnızca sunum sınırında yuvarlama yapın.

Performans

Her değer nesnesi, float değerlerden oluşan düz bir readonly yapıdır. İç içe geçmiş değiştirilebilir durum bulunmadığından, nesne oluşturma ve her dönüşüm derin kopya olmadan O(1) tek tahsisle gerçekleşir. Bir örneği belgeler arasında ek maliyet olmadan paylaşabilirsiniz. Bu referans sayfası için varsayılan performance_budget değeri wall_ms: 1500, peak_mb: 64 şeklindedir.

Güvenlik notları

Bu değer nesneleri hiçbir input/output (G/Ç) işlemi gerçekleştirmez, kullanıcı tarafından sağlanan bir sayfa boyutu adı dışında dize taşımaz ve harici kaynak tutamaçları bulundurmaz; dolayısıyla doğrudan bir saldırı yüzeyi sunmazlar. PageSize::fromName() bilinmeyen girdiyi sessizce varsayılan bir değere düşmek yerine bir istisnayla reddeder; böylece hatalı biçimlendirilmiş bir yapılandırma, beklenmeyen sayfa geometrisi üretmek yerine açıkça başarısız olur.

Uygunluk

Spesifikasyon	Madde	Konu
ISO 216:2007	A / B serisi	Kesilmiş kâğıt boyutu ölçüleri: A* / B* fabrikaları için (özetlenmiştir; ISO metni alıntılanmamış, hiçbir parça sabitlenmemiştir)

A ve B fabrika ölçüleri, punto cinsinden ifade edilen ISO 216 kesilmiş boyutlarına karşılık gelir. Kuzey Amerika boyutları (Letter, Legal, Tabloid), ISO temeli olmayan fiili sektör boyutlarıdır. ISO başvurusu, site alıntı politikası kapsamında özetlenmiştir. Hiçbir metin parçası birebir sabitlenmemiştir.

Ayrıca bakınız

• /modules/core/config/ — Config, şunları kullanır: PageSize ve Margin
• /modules/core/layout/ — bu ilkellerin yerleşimdeki tüketicileri
• /modules/core/graphics/ — Position, çizim koordinat uzayında
• /modules/core/contracts/ — Orientation, şununla birlikte: PageSize
• /modules/core/exception/ — PageLayoutException, kaynağı: fromName()