안정성: 실험적

CSS Grid(grid-template-areas)를 위한 유지 모드 레이아웃

한눈에 보기

옵트인 프리뷰. 유지 모드는 기본적으로 꺼져 있습니다. 기본 Streaming 모드는 이 모드가 존재하는 줄도 몰랐던 빌드와 바이트 단위로 동일합니다. 실제 그리드가 필요한 문서에 대해서만 켜고, 결과를 검증하세요.

기본적으로 렌더러는 단일 패스이며 스트리밍 방식입니다(ADR-001 참조). grid-template-areas로 선언된 CSS Grid는 한 번의 전진 패스로 배치할 수 없으므로, 스트리밍 엔진은 HTML_GRID_REQUIRES_RETAINED 경고를 발행하고 블록 흐름으로 되돌아갑니다. 유지 모드는 그 폴백을 실제 레이아웃으로 대체하는 옵트인입니다. Config::withCssLayoutMode(CssLayoutMode::Retained)는 확정 열 grid-template-areas 그리드를 GridLayoutEngine을 통해 라우팅하며, 이 엔진이 자식 요소들을 명명된 셀에 배치합니다.

설치

composer require nextpdf/core:^3

레이아웃 모드는 코어 패키지에 포함되어 제공됩니다. Config::withCssLayoutMode 옵트인은 @since 6.0.0입니다. 기본값은 여전히 CssLayoutMode::Streaming입니다.

개념 개요

CssLayoutMode는 Config의 타입 지정 enum입니다. Streaming은 기본값이자 역사적 동작이며, Retained는 문서를 그리드 엔진으로 옵트인합니다. 유지 모드는 제한된 유지 노드 집합(retainedNodeBudget, 기본값 50,000, [5,000, 100,000] 범위로 클램프됨)을 보유하여, 엔진의 메모리 규율을 버리지 않으면서도 스트리밍이 해석할 수 없는 그리드를 해석할 수 있게 합니다.

유지 모드가 켜져 있고 엔진이 열이 확정된 grid-template-areas 그리드를 만나면, 그리드를 실제로 배치합니다. 확정 열이란 콘텐츠 너비에 대해 해석된 고정 길이, 백분율, 또는 fr 단위입니다. 행은 자동으로 흐릅니다. 자식 요소들은 그 영역 이름이 선택하는 셀에 할당됩니다.

ADR-001은 스트리밍 불변 조건을 기록합니다. ADR-001에 대한 2026-06-28 개정은 유지 옵트인 예외 조항을 추가합니다. 스트리밍 기본값은 그대로이고 단일 패스 모델로 남으며, 유지 모드는 그리드 사례를 위한 명시적으로 제한된 옵트인 예외입니다.

경계 — 유지 모드가 배치하는 것, 여전히 폴백하는 것

유지 모드는 확정 열 grid-template-areas 사례만, 오직 그 사례만 처리합니다. 그 밖의 모든 것은 유지 모드가 켜져 있어도 HTML_GRID_REQUIRES_RETAINED 경고와 블록 폴백을 유지합니다.

grid-auto-flow: column과 grid-auto-flow: dense.
subgrid.
@container 쿼리.
자동 또는 본질적 열 트랙(auto, min-content, max-content).

이들은 연기된 슬라이스이지 조용한 공백이 아닙니다. 이들 중 하나에 의존하는 그리드는 블록 흐름으로 격하되며 그 사실을 여러분에게 알립니다.

Fail-closed 경계. 캡처 대 엔진 너비 불일치 — 측정된 콘텐츠 너비가 그리드 엔진이 해석한 너비와 일치하지 않는 경우 — 는 잘못 배치된 그리드를 만들어내는 대신 fail-closed 처리됩니다. 유지 모드는 또한 Safe CSS 렌더링 모드와 호환되지 않습니다. CssRenderingMode::Safe를 CssLayoutMode::Retained와 결합하면 구성 검증 시 IncompatibleRenderingModeException이 발생합니다. CssLayoutMode::Auto는 예약되어 있으며 NotImplementedException을 발생시킵니다.

API 표면

심볼	위치	역할
`Config::withCssLayoutMode(CssLayoutMode $mode): self`	`src/Core/Config.php`	문서를 `Streaming`(기본값) 또는 `Retained` 레이아웃으로 옵트인합니다.
`Config::withRetainedNodeBudget(int $budget): self`	`src/Core/Config.php`	유지 노드 집합을 제한합니다(`[5,000, 100,000]`, 기본값 `50,000`).
`Config::isRetainedMode(): bool`	`src/Core/Config.php`	문서가 유지 모드인지 보고합니다.
`CssLayoutMode`	`src/Core/`	`Streaming`, `Retained`; `Auto`는 예약됨(`NotImplementedException`).
`GridLayoutEngine`	`src/Html/`	유지 그리드 배치 엔진.
`IncompatibleRenderingModeException`	`src/Exception/`	Safe CSS 모드가 유지 모드와 결합될 때 발생합니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;

$config = (new Config())->withCssLayoutMode(CssLayoutMode::Retained);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . '.dashboard { display: grid; grid-template-columns: 1fr 2fr;'
    . '  grid-template-areas: "sidebar main"; }'
    . '.sidebar { grid-area: sidebar; } .main { grid-area: main; }'
    . '</style>'
    . '<div class="dashboard">'
    . '  <div class="sidebar">Navigation</div>'
    . '  <div class="main">Report content…</div>'
    . '</div>',
);
$doc->save(__DIR__ . '/grid.pdf');

코드 샘플 — 프로덕션

구성 시점에 비호환 모드 사례를 감지하고, 활성 모드를 다시 읽어 경로를 명시적으로 만듭니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;
use NextPDF\Exception\IncompatibleRenderingModeException;

try {
    $config = (new Config())
        ->withCssLayoutMode(CssLayoutMode::Retained)
        ->withRetainedNodeBudget(75_000);
    $config->validate();
} catch (IncompatibleRenderingModeException $e) {
    // Safe CSS mode and retained mode cannot combine. Choose one.
    throw $e;
}

$doc = Document::createStandalone($config);
assert($config->isRetainedMode());

$doc->addPage();
$doc->writeHtml($gridHtml);
$doc->save($out);

// A grid that needs a deferred feature (column auto-flow, subgrid, @container,
// or intrinsic columns) still emits HTML_GRID_REQUIRES_RETAINED and falls back
// to block flow. Inspect the advisory channel.

엣지 케이스 및 주의점

Streaming은 기본값으로 유지되며 바이트 단위로 동일합니다. 유지 모드는 여러분이 옵트인한 문서에 대해서만 출력을 변경합니다.
확정 열 grid-template-areas만 해당. 열 자동 흐름, 밀집 패킹, subgrid, @container, 본질적 열은 HTML_GRID_REQUIRES_RETAINED 경고와 블록 폴백을 유지합니다.
Safe 모드는 상호 배타적입니다. CssRenderingMode::Safe에 CssLayoutMode::Retained를 더하면 IncompatibleRenderingModeException을 던집니다.
Auto는 예약되어 있습니다. CssLayoutMode::Auto는 NotImplementedException을 발생시킵니다. 아직 사용 가능한 세 번째 옵션이 아닙니다.
너비 불일치는 fail-closed 처리됩니다. 캡처 대 엔진 콘텐츠 너비 불일치는 잘못 렌더링되지 않고 거부됩니다.

성능

유지 모드는 전체 문서 트리가 아니라 제한된 노드 집합을 보유합니다. retainedNodeBudget(기본값 50,000)이 그것을 상한 지웁니다. 그리드 배치는 노드 및 셀 개수에 선형입니다. 페이지당 performance_budget(wall_ms: 1500, peak_mb: 64)이 적용됩니다. 큰 그리드는 노드 예산을 100,000 상한까지 올릴 때 예산을 염두에 두어야 합니다.

보안 참고

유지 모드는 입력 표면을 넓히지 않습니다. HTML 보안 정책, CSS 속성 허용 목록, 파서 상한이 변경 없이 적용됩니다. 유지 노드 예산 자체가 자원 고갈 한계입니다. 엔진이 단일 문서에 대해 얼마만큼의 구조를 보유할지를 상한 짓습니다.

적합성

진술	사양	절
`grid-template-areas`는 그리드 셀에 이름을 붙이고, 명명된 영역은 항목을 배치합니다.	W3C CSS Grid Layout Module Level 1	§7.3
명시적 고정, 백분율, `fr` 트랙은 콘텐츠 너비에 대해 크기가 정해집니다.	W3C CSS Grid Layout Module Level 1	§7.2

이는 확정 열 grid-template-areas 부분집합의 프리뷰 구현입니다. 속성별 검증 상태는 CSS 지원 매트릭스에서 추적됩니다. 여기서는 종단 간 적합성을 주장하지 않습니다. 표준 텍스트는 재현되지 않습니다.