Legal — 심층 참조

한눈에 보기

• 순차 Bates 번호 스탬프를 페이지별 PDF 콘텐츠 스트림 조각으로 생성합니다.
• 세 개의 공개 타입: BatesNumberConfig(불변 구성), BatesNumberer(엔진), BatesPosition(여섯 케이스 위치 열거형).
• 각 조각은 자기 완결적입니다. 그래픽 상태가 저장되고 복원되므로, 추가해도 기존 페이지 콘텐츠를 절대 흐트러뜨리지 않습니다.
• 출력은 결정적입니다. 조각은 구성, 스탬프 텍스트, 페이지 크기의 순수 함수입니다.
• 이 모듈은 어떠한 예외도 발생시키지 않습니다. 범위를 벗어난 입력은 문서화된 폴백 규칙에 따라 점진적으로 처리됩니다.

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 티어 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포에서는 이 기능의 클래스가 로드되지 않습니다. 에디션을 비교하고 라이선스 받기.

기능별 라이선스 플래그는 없습니다. 이것은 Pro 에디션 기능입니다.

composer require nextpdf/pro:^3

공개 API 표면

심볼	매개변수	기본 동작	반환	발생시키는 예외 또는 실패	비고
BatesNumberConfig::__construct	string $prefix = '', string $suffix = '', int $startNumber = 1, int $padding = 5, BatesPosition $position = BatesPosition::BottomRight, float $fontSize = 9.0, string $fontFamily = 'Courier', float $opacity = 1.0, bool $useLayer = true, string $layerName = 'Bates Numbers', float $inset = 15.0	불변 외관 및 번호 매기기 구성	BatesNumberConfig	—	열한 개 속성 모두 public이며 readonly입니다.
BatesNumberConfig::formatNumber	int $pageIndex (0 기반)	prefix + 0으로 패딩된 (startNumber + pageIndex) + suffix	string	—	padding보다 넓은 숫자는 잘리지 않습니다.
BatesNumberConfig::getRange	int $pageCount	해당 실행의 첫 번째와 마지막 서식 스탬프	array{first: string, last: string}	—	pageCount >= 1을 가정합니다. 0이면 페이지 인덱스 -1을 서식화합니다.
BatesNumberer::__construct	BatesNumberConfig $config	구성을 바인딩	BatesNumberer	—	이 클래스는 final이며 readonly입니다.
BatesNumberer::generate	int $pageCount, array $pageSizes, string $prefix = '', int $startFrom = 1	기본 외관을 사용하는 정적 빠른 경로	list<string>	—	접미사, 위치, 글꼴, 불투명도, 레이어는 기본값을 유지합니다.
BatesNumberer::generateStreams	int $pageCount, list<array{width: float, height: float}> $pageSizes	페이지당 자기 완결적 조각 하나	list<string>	절대 예외를 발생시키지 않음. 누락된 크기 항목은 A4 세로로 폴백	조각 수는 pageCount와 같습니다. 초과 크기 항목은 무시됩니다.
BatesNumberer::buildPageStream	string $text, float $pageWidth, float $pageHeight	한 페이지의 스탬프 조각을 빌드	string	—	q/Q로 감쌉니다. 스탬프 텍스트는 리터럴 문자열 구문에 맞게 이스케이프됩니다.
BatesNumberer::getConfig	—	바인딩된 구성을 반환	BatesNumberConfig	—	—
BatesPosition	열거형 케이스 BottomLeft, BottomCenter, BottomRight, TopLeft, TopCenter, TopRight	문자열 기반 위치 어휘	—	—	백킹 값은 kebab-case입니다(예: bottom-right).
BatesPosition::coordinates	float $pageWidth, float $pageHeight, float $textWidth, float $inset = 15.0	PDF 네이티브 공간에서 스탬프 베이스라인의 X/Y	array{x: float, y: float}	—	원점은 좌측 하단입니다. 상단 행은 베이스라인을 상단 가장자리에서 inset만큼 배치합니다.

진입점 시그니처

public function __construct(
    public string $prefix = '',
    public string $suffix = '',
    public int $startNumber = 1,
    public int $padding = 5,
    public BatesPosition $position = BatesPosition::BottomRight,
    public float $fontSize = 9.0,
    public string $fontFamily = 'Courier',
    public float $opacity = 1.0,
    public bool $useLayer = true,
    public string $layerName = 'Bates Numbers',
    public float $inset = 15.0,
) {}

public static function generate(
    int $pageCount,
    array $pageSizes,
    string $prefix = '',
    int $startFrom = 1,
): array
public function generateStreams(int $pageCount, array $pageSizes): array
public function buildPageStream(string $text, float $pageWidth, float $pageHeight): string

public function coordinates(
    float $pageWidth,
    float $pageHeight,
    float $textWidth,
    float $inset = 15.0,
): array

동작 계약

번호 매기기

BatesNumberConfig::formatNumber는 startNumber + pageIndex를 계산하고, 그 숫자를 padding 자릿수까지 0으로 왼쪽 패딩한 뒤, prefix와 suffix로 감쌉니다. getRange는 페이지 수에 대한 첫 번째와 마지막 서식 스탬프를 반환합니다. 이를 사용하여 여러 프로덕션에 걸쳐 연속 번호 매기기를 이어갑니다.

조각 해부

각 조각은 순서대로 다음과 같습니다: 그래픽 상태 저장(q), 채우기 색상 연산자, 선택적 마크드 콘텐츠 시작, 스탬프를 위치시키고 표시하는 텍스트 블록, 선택적 마크드 콘텐츠 종료, 복원(Q). 좌표와 글꼴 크기는 소수점 여섯 자리로 직렬화되므로, 동일한 입력은 동일한 바이트를 생성합니다. 스탬프 텍스트는 리터럴 문자열에 진입하기 전에 \, (, )를 이스케이프합니다.

글꼴 바인딩

텍스트 블록은 고정된 글꼴 리소스 이름 /BatesFont를 선택합니다. 임베딩하는 페이지의 리소스 딕셔너리는 그 이름을 구성된 fontFamily와 일치하는 글꼴에 매핑해야 하며, 그 패밀리는 글꼴 레지스트리에서 해석되어야 합니다. 조각 생성 자체는 레지스트리를 절대 참조하지 않습니다.

배치

BatesPosition::coordinates는 PDF 네이티브 공간에서 스탬프 베이스라인을 계산합니다. 원점은 좌측 하단입니다. 가운데와 오른쪽 배치는 추정된 텍스트 너비를 뺍니다: 바이트 길이 × 0.6 × 글꼴 크기로, 등폭 근사값입니다. 비례 글꼴과 멀티바이트 텍스트는 그 추정값을 이동시킵니다. 왼쪽 배치는 그것에 의존하지 않습니다.

레이어

useLayer가 활성화되면(기본값), 조각은 텍스트를 BDC와 EMC 마크드 콘텐츠 연산자 사이에 괄호로 묶습니다. 마크드 콘텐츠 이름은 /Lyr_<name> 형태이며, layerName에서 단어가 아닌 문자를 밑줄로 치환하여 파생됩니다. 이 괄호 묶음은 조각 수준에만 해당합니다: 문서에 해당 선택적 콘텐츠 그룹을 등록하는 것 — 뷰어에서 레이어를 토글 가능하게 만드는 단계 — 은 임베딩하는 작성기의 몫입니다.

불투명도

1.0 미만의 opacity는 더 밝은 그레이스케일 채우기로 방출됩니다. 완전히 불투명한 스탬프는 검은색으로 렌더링됩니다.

범위

엔진은 구성된 그대로 정확히 Bates 번호를 적용합니다. 번호가 매겨진 문서가 법정에서 허용 가능하거나 법적으로 유효하다고 주장하지 않습니다. 번호 매기기 체계, 보존, 증거 처리는 고객의 책임으로 남습니다. 절차적 충분성에 대해서는 법무 및 규정 준수 팀에 문의하십시오.

엣지 케이스 및 실패 모드

• generateStreams는 pageSizes 불일치에서 절대 예외를 발생시키지 않습니다. 누락된 항목은 A4 세로, 595.276 × 841.890 포인트로 폴백합니다. 초과 항목은 무시됩니다.
• 조각 수는 항상 pageCount와 같습니다.
• padding보다 넓은 숫자는 잘리지 않습니다. 스탬프 텍스트가 단순히 길어질 뿐입니다.
• getRange는 pageCount >= 1을 가정합니다. 0이면 페이지 인덱스 -1, 즉 startNumber - 1을 서식화합니다.
• 불투명도는 그레이스케일 밝기 조정이지 ExtGState 투명도가 아닙니다. 스탬프 아래에 겹치는 콘텐츠는 블렌딩되지 않습니다.
• \, (, ) 이외의 스탬프 바이트는 인코딩되지 않은 채 통과합니다. 비 ASCII 텍스트에 대한 인코딩 정확성은 바인딩된 글꼴에 달려 있습니다.
• Bates 표시는 오버레이 콘텐츠입니다. 페이지의 어떤 것도 편집(redact)하거나, 제거하거나, 암호화하지 않습니다.
• 이 모듈은 어떠한 암호화 연산도 수행하지 않습니다. FIPS 모드는 동작을 변경하지 않습니다.

적합성

동작	참조	상태
BDC/EMC 마크드 콘텐츠 연산자를 통한 레이어 괄호 묶음	ISO 32000-2:2020 §8.11.3.2	부분 — 조각은 괄호 묶음을 방출하며, 선택적 콘텐츠 그룹 등록은 임베딩하는 작성기의 단계입니다

이 행들은 모듈이 기반으로 삼는 사양을 기록한 것이지 인증이 아닙니다. NextPDF는 어떠한 적합성 인증도 보유하고 있지 않습니다. 이 표는 또한 법적 유효성이나 증거적 충분성에 대한 명시가 아닙니다.

개발 참고 사항

• 조각은 순수 문자열 값입니다. 직접 바이트 비교로 테스트하십시오. 문서 컨텍스트는 필요하지 않습니다.
• buildPageStream은 public이며 독립적으로 단위 테스트할 수 있습니다: 미리 서식화된 텍스트와 명시적 페이지 치수를 전달하십시오.
• 여러 프로덕션에 걸친 연속 번호 매기기의 경우, 이전 실행에서 startNumber를 시드하고 getRange 출력을 프로덕션 로그에 기록하십시오.
• 레이어 이름은 단어 문자로 정제됩니다. 마크드 콘텐츠 이름이 검사 도구에서 읽기 쉽게 유지되도록 ASCII 레이어 이름을 선호하십시오.

발행 경계

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

관련 항목

• Legal 기능 개요
• Merge — 심층 참조
• Security — 심층 참조