Pro 에디션

Flow Layout

한눈에 보기

NextPDF Pro는 일련의 플로우 요소 — 텍스트, 이미지, 표, 스페이서 — 를 페이지에 배치하며, 각각에 구체적인 페이지와 위치를 할당합니다. 페이지 나눔 동작은 선택할 수 있습니다. 그리디, 고아 회피, 또는 함께 유지입니다.

제공 여부 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)에서 제공되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 기능별 별도의 라이선스 플래그는 없으며, Pro 봉투가 이를 활성화합니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/pro:^3

개념 개요

스트리밍 레이아웃 엔진은 플로우 요소 목록과 콘텐츠 영역을 받은 뒤, 요소를 순서대로 순회하며 각각에 페이지와 위치를 할당합니다. 요소가 남은 세로 공간에 맞지 않으면, 엔진은 구성된 전략에 따라 새 페이지를 시작합니다.

StreamingLayoutEngine — 엔진입니다. LayoutRegion(페이지당 콘텐츠 영역)과 PageBreakStrategy로 구성됩니다. 배치된 요소의 LayoutResult를 반환합니다.
FlowElement / FlowElementType — 요소 모델입니다. 텍스트와 표는 페이지에 걸쳐 나뉠 수 있으며, 엔진은 이미지와 스페이서를 원자적으로 배치합니다.
PageBreakStrategy — 세 가지 동작을 가진 enum입니다.
- Greedy — 다음 요소가 맞지 않는 즉시 나눕니다.
- AvoidOrphans — 작은 공간만 남았을 때 일찍 나누어, 새 페이지 상단에 단일 요소가 남는 것을 피합니다.
- KeepTogether — keep-with-next 플래그를 존중하여 가능한 경우 쌍을 이루는 요소가 같은 페이지에 머무르도록 합니다.

Flow Layout은 요소 배치 엔진입니다. 페이지와 위치 할당을 계산하며, HTML이나 CSS 렌더링 엔진이 아닙니다. HTML-to-PDF에는 Core HTML 파이프라인을 사용하십시오.

이렇게 동작하는 이유

엔진은 한 번의 정방향 패스로 각 요소에 페이지와 위치를 할당합니다. 나중에 다시 흐름을 재배치하기 위해 전체 문서 트리를 버퍼링하지 않습니다. 이는 문서가 아무리 길게 실행되어도 메모리를 일정하게 유지하며, 비용을 요소 수에 선형으로 만듭니다. 각 페이지 나눔 결정은 현재 커서와 선택된 전략에 대한 지역 술어입니다. 그래서 그리디, 고아 회피, 함께 유지가 모두 동일한 스트리밍 순회 안에서 해결됩니다. 그 대가는 정방향 확정입니다. 지나치게 키가 큰 요소는 재조정되기보다 넘치며, 함께 유지는 쌍을 이루는 두 요소가 같은 페이지를 공유할 때만 유효합니다.

설계 배경: 고용량 문서 생성.

API 표면

클래스	책임
`StreamingLayoutEngine`	플로우 요소에 페이지와 위치를 할당합니다.
`FlowElement`, `FlowElementType`	요소 모델과 유형 enum입니다.
`LayoutRegion`	페이지당 콘텐츠 영역입니다.
`PageBreakStrategy`	페이지 나눔 동작 enum입니다.
`LayoutResult`, `PlacedElement`	배치 출력입니다.

코드 샘플 — 빠른 시작

use NextPDF\Pro\FlowLayout\{StreamingLayoutEngine, LayoutRegion, PageBreakStrategy};

$engine = new StreamingLayoutEngine(
    region:   new LayoutRegion(/* x, y, width, height */),
    strategy: PageBreakStrategy::AvoidOrphans,
);
$result = $engine->layout($elements);

코드 샘플 — 프로덕션

$result = $engine->layout($elements);
foreach ($result->placements as $placed) {
    $logger->debug('flow.placed', [
        'page' => $placed->pageIndex,
        'type' => $placed->element->type->value,
    ]);
}

엣지 케이스 및 함정

엔진은 영역보다 키가 큰 요소도 여전히 배치하지만 넘칠 수 있습니다. 영역 높이 안에서 요소 크기를 지정하십시오.
KeepTogether는 둘 다 한 페이지에 맞을 때만 쌍을 함께 유지합니다.
AvoidOrphans는 나누기 전에 최소 두 요소 높이를 예약합니다.

성능

레이아웃은 요소 수에 선형적입니다. 엔진은 스트리밍입니다. 전체 문서 트리를 보관하지 않습니다.

보안 참고

Flow Layout은 제공한 요소 메타데이터를 다룹니다. I/O를 수행하지 않습니다.

적합성

Flow Layout은 NextPDF 배치 동작을 구현합니다. 외부 레이아웃 표준을 대상으로 삼지 않습니다.

동작 계약

StreamingLayoutEngine은 LayoutRegion과 PageBreakStrategy로 구성되며, 구체적인 페이지 및 위치 할당이 적용된 배치 요소의 LayoutResult를 반환합니다.
PageBreakStrategy는 세 가지 동작을 가집니다. Greedy(다음 요소가 맞지 않을 때 나눔), AvoidOrphans(최소 두 요소 높이를 예약하며 일찍 나눔), KeepTogether(keep-with-next를 존중하여 둘 다 맞을 때 쌍을 이루는 요소가 한 페이지에 머무름).
텍스트와 표는 페이지에 걸쳐 나뉠 수 있으며, 이미지와 스페이서는 원자적으로 배치됩니다. 영역보다 키가 큰 요소도 여전히 배치되지만 넘칠 수 있습니다.
엔진은 스트리밍입니다. 전체 문서 트리를 보관하지 않으며 I/O를 수행하지 않습니다.
이는 요소 배치 엔진입니다. 페이지와 위치 할당을 계산하며, HTML이나 CSS 렌더링 엔진이 아닙니다.

Enterprise 경계 참고

Enterprise는 Flow Layout 동작을 변경하지 않습니다. Enterprise는 별도로 문서화된 상위 등급 기능을 더하며, 그것들은 배치 엔진을 사용하는 데 필요하지 않습니다.

Core 폴백 / 대안

페이지 나눔 전략을 갖춘 Core 요소 배치 엔진은 없습니다. HTML-to-PDF 렌더링에는 오픈 소스 Core HTML 파이프라인을 사용하십시오. /modules/html/를 참조하십시오.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 티켓 접두사는 범위 밖입니다.

함께 보기

Flow Layout — 심층 참조 — 전체 클래스 및 메서드 참조.
Document — 문서 조립.
Core HTML 모듈 — HTML-to-PDF 렌더링.